~bzr-pqm/bzr/bzr.dev

.. Этот файл в формате ReStructuredText - он может быть отформатирован в HTML,
.. или текст. В будущем планируется выделять примеры команд и автоматически
.. тестировать их.

.. Данный текст сначала был на Wiki
.. http://bazaar.canonical.com/IntroductionToBzr
.. но был перемещен в дерево исходного кода что бы синхронизироваться
.. с исходным кодом и возможно автоматически тестироваться.

==============
Учебник Bazaar
==============

Текущая версия для bzr-0.91, 2007-08


Введение
========

Если вы уже знакомы с распределенными системами контроля версий, то можете
сразу перейти к "Представляемся Bazaar". Если, с другой стороны, вы знакомы с
системами контроля версий, но не знакомы с распределенными системами, тогда
стоит начать с "Чем отличаются распределенные системы". Иначе, возьмите кофе
или чай, расположитесь поудобнее и продолжим чтение.

Назначение контроля версий
==========================

Есть шансы, что вы уже работали с какими-либо текстовыми данными -- исходниками
программ, Web-сайтами, или конфигурационными файлами с которыми имеют дело
администраторы систем Unix в /etc. Также есть хорошие шансы, что вы делали
ошибки, которые вызывали потом глубокое сожаление. Возможно вы удалили
конфигурационный файл для вашего почтового сервера, или повредили исходный код
любимого проекта. Не важно что конкретно случилось, но вы просто удалили важную
информацию которую вы безнадежно хотели бы вернуть. Если такое когда либо
случалось с вами, то вы возможно готовы для Bazaar.

Системы контроля версий, такие как Bazaar дают возможность отслеживать
изменения для каталога, который они изменяют в нечто более сложное, что
называется **ветка**. Ветка не только сохраняет то как каталог выглядит в
данный момент, но также как он выглядел в различные моменты в прошлом. Затем,
когда вы сделаете что-то, что бы вы не хотели делать, вы сможете восстановить
каталог в том виде как он выглядел в какой-то момент в прошлом.

Системы контроля версий дают пользователям возможность сохранять изменения на
ветке "фиксируя **ревизию**". Созданная ревизия фактически является сводкой
изменений, которые были сделаны с последнего момента когда дерево было
сохранено.

Эти ревизии имеют также и другое назначение. Например, можно комментировать
ревизии, записав, что значит данный набор изменений, через необязательную
запись в журнале. Реальные записи в журнале могут быть похожи на "Исправлен
Web-шаблон для закрытия таблицы" и "Добавлена поддержка SFTP. Исправлен #595"

Мы храним этот журнал, что бы позже, в случае каких-либо проблем с SFTP, можно
было определить когда могла произойти проблема.

Чем отличаются распределенные системы
-------------------------------------

Многие системы контроля версий хранят данные на серверах. Если кто-то хочет
работать с кодом, который хранится в системе тогда ему нужно установить
соединение с сервером и "создать рабочую копию" кода. При этом создается
каталог в котором можно менять файлы и затем фиксировать изменения. Клиент
системы затем соединяется с сервером системы и сохраняет изменения. Этот метод
известен как централизованная модель.

Централизованная модель может иметь некоторые недостатки. Централизованная
система требует наличия соединения с сервером для любых действий по контролю
версий. Это может быть проблематичным если сервер находится на другой машине в
интернете, а клиент - нет. Или, хуже, клиент **в** интернете, а сервер - нет.

Распределенные системы контроля версий обходят эту проблему сохраняя ветки на
той же машине на которой находится клиент. В случае с Bazaar, ветка находится в
том же самом месте, что и код хранящийся под контролем версий. Это позволяет
пользователю сохранять (**фиксировать**) изменения когда он захочет -- даже без
сетевого подключения. Пользователю нужен доступ к интернету только когда он
хочет получить доступ к чьей-либо ветке в другом месте.

Общее требование, что многие люди хотят отслеживать изменения для каталога,
такие как изменения файлов и изменения в подкаталогах. Отслеживать это
"руками" ужасный процесс, который со временем становится громоздким. До тех пор
пока вы не попробуете систему контроля версий, такую как Bazaar. Такие
инструменты автоматизируют процесс сохранения данных, создавая **ревизии**
дерева каталога когда пользователь запрашивает сделать это.

Системы контроля версий, такие как Bazaar, могут делать намного больше чем
просто хранить изменения и отменять ошибочные действия. Например, с помощью
Bazaar разработчики могут взять изменения кода на одной ветке и объединить их
со связанной веткой -- даже если эти изменения хранятся на ветке которую создал
кто-то другой. Это позволяет разработчикам сотрудничать без необходимости
открывать доступ на запись к репозиторию.

Bazaar помнит ''предков'' ревизии: предыдущие ревизии на которых основана
текущая ревизия. Одна ревизия может иметь больше одного прямого потомка, каждый
из которых со своими изменениями, что представляет дивергенцию в эволюции
дерева. Создание веток в Bazaar позволяет нескольким людям сотрудничать в
эволюции проекта, без необходимости работать жестко по шагам. Создание веток
может быть полезным даже для одного разработчика.

Представляемся Bazaar
=====================

Bazaar устанавливает единственную новую команду, **bzr**. Все возможности
предоставляются через под-команды этой команды. Вы можете просмотреть краткую
справку командой ``bzr help``. Некоторые идеи группируются по темам,
используйте ``bzr help topics`` для списка доступных тем.

Одна из функций системы контроля версий -- отслеживать кто сделал изменения. В
распределенных системах для этого требуется идентифицировать каждого автора
уникально в глобальном плане. Большинство людей уже имеют такой идентификатор:
email адрес. Bazaar достаточно умен, что бы автоматически создавать email адрес
из текущего имени и адреса хоста. Если вам не нравится предположение которое
делает Bazaar вы сможете выбрать из трех опций:

 #. Установить email адрес через ``bzr whoami``. Это наиболее простой путь.

    Что бы установить такой глобальный идентификатор, используйте::

     % bzr whoami "Ваше Имя <email@example.com>"

    Если вы хотите использовать разные адреса для разных веток, то зайдите
    в каталог с веткой и используйте::

     % bzr whoami --branch "Ваше Имя <email@example.com>"

 #. Установить email адрес в ``~/.bazaar/bazaar.conf`` [1]_, добавив следующие
    строчки. Заметьте, что ``[DEFAULT]`` зависит от регистра символов::

        [DEFAULT]
        email=Ваше Имя <email@isp.com>

    Как и выше вы можете переопределить эти установки для каждой ветки
    создав секцию для ветки в ``~/.bazaar/locations.conf`` и добавив
    следующие строчки::

        [/путь/к/ветке]
        email=Ваше Имя <email@isp.com>

 #. Переопределить два предыдущих способа, установив ваш полный email адрес в
    глобальную переменную среды ``$BZR_EMAIL``, или ``$EMAIL`` (``$BZR_EMAIL``
    имеет больший приоритет).

.. [1] Для Windows пользовательские файлы конфигурации могут быть найдены в
   каталоге с данными приложений. Таким образом вместо
   ``~/.bazaar/branch.conf`` конфигурация может быть найдена в:
   ``C:\Documents and Settings\<пользователь>\Application Data\Bazaar\2.0\branch.conf``. Там же могут
   быть найдены ``locations.conf``, ``ignore`` и каталог ``plugins``.

Создаем ветку
=============

История по-умолчанию хранится на ветке в каталоге .bzr. В будущих версиях
Bazaar будут средства для хранения истории в отдельном репозитории, который
также сможет быть удаленным.

Мы создаем новую ветку выполнив ``bzr init`` в уже созданном каталоге::

    % mkdir tutorial
    % cd tutorial
    % ls -a
    ./  ../
    % pwd
    /home/mbp/work/bzr.test/tutorial
    %
    % bzr init
    % ls -aF
    ./  ../  .bzr/
    %

Как и в CVS здесь три класса файлов: неизвестные, игнорируемые и под контролем
версий. Команда **add** ставит файл под контроль версий, т.е. изменения в нем
будут записываться системой::

    % echo 'hello world' > hello.txt
    % bzr status
    unknown:
      hello.txt
    % bzr add hello.txt
    added hello.txt
    % bzr status
    added:
      hello.txt

Если вы добавили не тот файл просто сделайте ``bzr remove``, что бы сделать его
опять неизвестным. Рабочая копия файла не будет удалена в этом случае, хотя она
может быть удалена в других случаях [2]_.

.. [2] ``bzr remove`` удалит рабочую копию если она находится под контролем
   версий, но не имеет изменений с последней зафиксированной версии. Вы
   можете оставить файл указав опцию ``--keep`` для ``bzr remove``, или
   удалить с опцией ``--force``.

Размещение веток
================

Вся история хранится на ветке, которая является всего лишь каталогом на диске
содержащим файлы управления. По-умолчанию здесь нет отдельного репозитория, или
базы данных как в svn, или svk. По желанию вы можете создать репозиторий (см.
команду ``bzr init-repo``). Это можно сделать в случае очень больших веток, или
большого количества веток для проекта среднего размера.

Мы обычно обращаемся к веткам на нашем компьютере просто передав имя каталога
содержащего ветку. bzr также поддерживает доступ к веткам через http и sftp,
например::

    % bzr log http://bazaar-vcs.org/bzr/bzr.dev/
    % bzr log sftp://bazaar-vcs.org/bzr/bzr.dev/

Установив для bzr плагины можно также осуществлять доступ к веткам с
использованием rsync.

Смотрите секцию `Публикация ветки`_ что бы получить больше информации о том как
поместить свою ветку в нужное место.

Просмотр изменений
==================

Как только вы закончили свою работу, вы захотите **зафиксировать** ее в истории
ревизий. Хорошая практика фиксировать изменения достаточно часто: когда
заработала новая функциональность, исправлена ошибка, или улучшен код, или
документация. При этом стоит проверить, что код компилируется и проходит все
тесты перед фиксацией, что бы быть уверенным, что каждая ревизия в хорошем
состоянии. Также можно просмотреть свои изменения, для уверенности, что вы
фиксируете именно то, что хотели и получить шанс проверить свою работу перед
тем как записать ее постоянно.

Две команды bzr особенно полезны здесь: **status** и **diff**.

bzr status
----------

Команда **status** показывает какие изменения были сделаны в рабочем каталоге
с момента последней ревизии::

    % bzr status
    modified:
       foo

``bzr status`` скрывает "неинтересные" файлы которые, либо не менялись, либо
игнорируются. Также команде status могут быть переданы необязательные имена
файлов, или каталогов для проверки.

bzr diff
--------

Команда **diff** показывает изменения в тексте файлов в стандартном формате
diff. Вывод этой команды может быть передан другим командам, таким как
''patch'', ''diffstat'', ''filterdiff'' и ''colordiff''::

    % bzr diff
    === added file 'hello.txt'
    --- hello.txt   1970-01-01 00:00:00 +0000
    +++ hello.txt   2005-10-18 14:23:29 +0000
    @@ -0,0 +1,1 @@
    +hello world

С опцией ``-r`` дерево файлов сравнивается с ранней ревизией, или показываются
изменения между двумя ревизиями::

    % bzr diff -r 1000..          # изменения начиная с r1000
    % bzr diff -r 1000..1100      # изменения c 1000 до 1100

Опция ``--diff-options`` говорит bzr запустить внешнюю программу diff, передав
ей опции. Например::

    % bzr diff --diff-options --side-by-side foo

Некоторые проекты предпочитают показывать префиксы в начале текста изменений
для старых (old) и новых (new) файлов. Опция ``--prefix`` может быть
использована для установки такого префикса. Плюс к этому команда ``bzr diff
-p1`` выводит префиксы в форме которая подходит для команды ``patch -p1``.

Фиксация изменений
==================

Когда состояние рабочего дерева подходит для сохранения оно может быть
**зафиксировано** на ветке, что создаст новую ревизию содержащую снимок
состояния дерева.

bzr commit
----------

Команде **commit** можно передать сообщение описывающее изменения в ревизии.
Она также записывает идентификатор пользователя, текущее время и временную
зону, плюс список измененных файлов и их содержимого. Сообщение описывающее
изменения определяется через опцию ``-m``, или ``--message``. Можно также
вводить сообщения состоящие из нескольких строк; в большинстве оболочек вы
можете сделать это оставив открытую кавычку в конце строки.

::

    % bzr commit -m "добавлен первый файл"

Также можно использовать опцию ``-F``, для получения сообщения из файла.
Некоторые люди делают заметки изменений во время работы над ними, а затем
просматривают изменения, что бы быть уверенными, что они сделали то, что хотели
сделать. (Этот файл может быть также полезен когда вы возвращаетесь к своей
работе после перерыва.)

Сообщение из текстового редактора
=================================

Если вы не используете опции ``-m`` и ``-F`` тогда bzr откроет текстовый
редактор для ввода сообщения. Какой редактор запускать может быть настроено
через переменные среды ``$VISUAL``, или ``$EDITOR``, которые могут быть
переопределены опцией ``editor`` в файле ``~/.bazaar/bazaar.conf``; опция
``$BZR_EDITOR`` переопределяет все описанные выше настройки. Если вы выходите
из редактора без каких-либо изменений, то фиксация будет прервана.

Файл который открывается в редакторе содержит горизонтальную линию. Часть файла
ниже этой линии включена только для информации и не будет частью сообщения об
изменениях. Ниже линии показывается список файлов которые были изменены. Для
создания сообщения вам надо написать свое сообщение выше линии, сохранить его и
выйти из редактора.

Если вы хотите увидеть изменения содержимого файлов которые будут
зафиксированы, при редактировании сообщения вам нужно указать опцию
``--show-diff`` для команды ``commit``. Эта опция добавит изменения в файл
который будет открыт в редакторе ниже линии и списка измененных файлов. Это
значит, что вы можете читать изменения при редактировании сообщения, но они не
будут включены в сообщение когда вы закончите редактировать. Если вы хотите,
что бы части изменений были включены в сообщение вы можете скопировать и
вставить их выше ограничительной линии.

Выборочная фиксация
-------------------

Если вы передадите список имен файлов, или каталогов после команды commit, то
будут зафиксированы только изменения для переданных объектов. Например::

    % bzr commit -m "исправления документации" commit.py

По умолчанию bzr всегда фиксирует все изменения для дерева, даже если запущен
из подкаталога. Что бы зафиксировать только изменения от текущего каталога
и ниже, используйте::

    % bzr commit .


Удаление не зафиксированных изменений
=====================================

Если вы сделали какие-либо изменения и не хотите оставлять их, используйте
команду **revert**, что бы вернутся к состоянию предыдущей ревизии. Хорошая
идея, использовать сначала ``bzr diff`` для просмотра изменений. По умолчанию
команда revert отменяет изменения на всем дереве, но если ей переданы имена
файлов, или каталогов то будут затронуты только они. ``bzr revert`` также
очищает список ревизий ожидающих объединения.

Игнорирование файлов
====================

Многие деревья с исходным кодом содержат файлы которые не нужно хранить под
контролем версий, например резервные файлы текстового редактора, объектные
файлы и собранные программы. Вы можете просто не добавлять их, но они всегда
будут обнаруживаться как неизвестные. Вы также можете сказать bzr игнорировать
их добавив их в файл ``.bzrignore`` в корне рабочего дерева.

Этот файл содержит список шаблонов файлов, по одному в каждой строчке. Обычное
содержимое может быть таким::

    *.o
    *~
    *.tmp
    *.py[co]

Если шаблон содержит слеш, то он будет сопоставлен с полным путем начиная от
корня рабочего дерева; иначе он сопоставляется только с именем файла. Таким
образом пример выше игнорирует файлы с расширением ``.o`` во всех
подкаталогах, но пример ниже игнорирует только ``config.h`` в корне рабочего
дерева и HTML файлы в каталоге ``doc/``::

    ./config.h
    doc/*.html

Для получения списка файлов которые игнорируются и соответствующих им шаблонов
используйте команду ``bzr ignored``::

    % bzr ignored
    config.h                 ./config.h
    configure.in~            *~

Нет проблем если шаблон для игнорирования подходит для файла под контролем
версий, или вы добавили файл который игнорируется. Шаблоны не имеют никакого
эффекта на файлы под контролем версий, они только определяют показываются
неизвестные файлы, или просто игнорируются.

Файл ``.bzrignore`` обычно должен быть под контролем версий, что бы новые копии
ветки видели такие же шаблоны::

    % bzr add .bzrignore
    % bzr commit -m "Добавлены шаблоны для игнорирования"


Глобальные шаблоны для игнорирования
------------------------------------

Обычно есть файлы которые нужно игнорировать и они не специфичны для отдельных
проектов, а скорее специфичны для пользователя. Например, временные файлы
текстового редактора, или персональные временные файлы. Вместо того, что бы
добавлять их для игнорирования в каждом проекте, bzr поддерживает глобальный
файл игнорирования ``~/.bazaar/ignore`` [1]_. Он имеет такой же синтаксис, что
и файл игнорирования для каждого проекта.


Просмотр истории
================

bzr log
-------

Команда ``bzr log`` показывает список предыдущих ревизий. Команда ``bzr log
--forward`` делает тоже самое, но в хронологическом порядке, показывая более
поздние ревизии в конце.

Как и ``bzr diff``, ``bzr log`` поддерживает опцию ``-r``::

    % bzr log -r 1000..          # Ревизия 1000 и все после нее
    % bzr log -r ..1000          # Все до и включая r1000
    % bzr log -r 1000..1100      # изменения с 1000 до 1100
    % bzr log -r 1000            # Изменения только для ревизии 1000


Статистика ветки
================

Команда ``bzr info`` показывает суммарную информацию о рабочем дереве и истории
на ветке.


Каталоги под контролем версий
=============================

bzr может контролировать файлы и каталоги, отслеживая переименования и
упрощая их последующее объединение::

    % mkdir src
    % echo 'int main() {}' > src/simple.c
    % bzr add src
    added src
    added src/simple.c
    % bzr status
    added:
      src/
      src/simple.c


Удаление файлов
===============

Вы можете удалить файл, или каталог из под контроля версий просто удалив их
из рабочего каталога. Это немного отличается от CVS, которая требует что бы вы
также сделали ``cvs remove``.

``bzr remove`` удаляет файл из под контроля версий, но может и не удалять
рабочую копию файла [2]_. Это удобно когда вы добавили не тот файл, или решили,
что файл на самом деле не должен быть под контролем версий.

::

    % rm -r src
    % bzr remove -v hello.txt
    ?       hello.txt
    % bzr status
    removed:
      hello.txt
      src/
      src/simple.c
    unknown:
      hello.txt

Если вы вдруг удалили не тот файл, то вы можете использовать ``bzr revert`` что
бы восстановить его.


Ветвление
=========

Часто вместо того что бы начинать свой собственный проект, вы хотите предложить
изменения для уже готового проекта. Что бы сделать это вам нужно получить копию
готовой ветки. Так как эта копия может быть потенциальной новой веткой эта
команда называется **branch**::

    % bzr branch http://bazaar-vcs.org/bzr/bzr.dev
    % cd bzr.dev

Эта команда копирует полную историю ветки и после этого вы можете делать все
операции с ней локально: просматривать журнал, создавать и объединять другие
ветки. Здесь также есть опция для получения только части истории если это
необходимо.

Копию другой ветки можно также получить просто скопировав ее каталог,
развернув архив, или скопировав удаленно через такую утилиту как rsync.


Следование за изменениями основного проекта
===========================================

Вы можете обновлять свою ветку из родительской через получение ее изменений::

    % bzr pull

После этого локальный каталог будет копией родительского. Это включает и
''историю ревизий'' - список изменений сделанных на родительской ветке, а не
объединенных с других веток.

Эта команда работает только если локальная ветка, либо более старая копия
родительской ветки без новых фиксаций, либо все последние фиксации уже были
объединены с родительской веткой.

Объединение со связанных веток
==============================

Если две ветки разошлись (обе имеют уникальные изменения) тогда ``bzr merge`` -
это подходящая команда для использования. Объединение автоматически вычислит
изменения которые существуют на объединяемой ветке и отсутствуют в локальной
ветке и попытается объединить их с локальной веткой.

::

  % bzr merge URL

В случае конфликта при объединении будут созданы три файла с одними именем, но
разными расширениями. Файл с общими изменениями будет с расширением ".BASE",
файл с локальными изменениями будет с расширением ".THIS" и файл с изменениями
из объединяемой ветки будет с расширением ".OTHER". Используя такую программу
как kdiff3 вы теперь сможете достаточно легко объединить их в один файл. Для
фиксации изменений вам нужно переименовать объединенный файл (".THIS") в файл с
оригинальным именем. И для завершения исправления конфликта нужно использовать
команду resolve, которая удалит файлы ".OTHER" и ".BASE". Команда commit будет
выдавать ошибку пока существует один из файлов с расширением .BASE, .THIS, или
.OTHER.

::

  % kdiff3 file.BASE file.OTHER file.THIS
  % mv file.THIS file
  % bzr resolve file

[**TODO**: описать маркеры конфликтов внутри файлов]


Публикация ветки
================

Для публикации ветки bzr вам не нужен специализированный сервер, нужен просто
обычный Web-сервер. Просто перенесите файлы на ваш сервер, включая каталог
.bzr. Можно опубликовать ветку (или изменения на ветке) одним из следующих трех
способов:

* Лучший способ - использовать для этого сам bzr.

  ::

    % bzr push sftp://servername.com/path/to/directory

  (Каталог назначения должна быть создан заранее, если только не указана
  опция ``--create-prefix``)

* Другой способ - плагин ``rspush`` который включен в BzrTools и использует
  rsync для публикации изменений в истории ревизий и рабочем дереве.

* Вы также можете скопировать файлы руками, переслав архив, или используя
  rsync, или другой метод пересылки. Обычно это менее безопасно чем
  использовать команду ``push``, но может быть быстрее и проще в каких-то
  ситуациях.

Перемещение изменений между деревьями
=====================================

Это случается и с лучшими из нас: в какой-то момент вы делаете изменения не в
том дереве файлов. Возможно потому, что вы случайно начали работать не в том
каталоге, либо изменений оказались больше чем вы ожидали и вы решили создать
для них новую ветку.

Для перемещения изменений из одного дерева в другое используйте

::

  % cd NEWDIR
  % bzr merge --uncommitted OLDDIR

Эта команда перенесет все не зафиксированные изменения с ветки OLDDIR на ветку
NEWDIR. Команда не будет переносить зафиксированные изменения, даже если они
могли бы быть объединены с NEWDIR обычным объединением. Изменения также
остаются и в OLDDIR, но вы можете использовать ``bzr revert OLDDIR`` для их
удаления, как-то только убедитесь, что с NEWDIR все нормально.

NEWDIR не обязательно должен быть копией OLDDIR, но они должны быть связанными
ветками. Чем больше они отличаются, тем больше шанс возникновения конфликтов.