Готовый перевод Bazaar is a distributed version control system / Базар - распределенная система контроля версий: doc/en/tutorials/tutorial.txt

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

.. Ранее этот текст был на wiki на
.. http://bazaar.canonical.com/IntroductionToBzr
.. но был перемещён в дерево с исходниками, т.к. это может позволить сохранить синхронизированность с
.. исходниками и возможно позволит производить автоматическую проверку.

===============
Руководство по Bazaar
===============

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

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

Если вы уже знакомы с контролем распределенных изменений, тогда вы свободно можете пропустить всё до раздела "Представляя себя Базару". С другой стороны, если вы знакомы с контролем изменений, но не распределенных, тогда начните с "Отличия РСКВ". Иначе, заварите кофе или чай, устраивайтесь поудобнее и будьте готовы наверстать упущенное.

Цели контроля изменений
================================

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

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

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

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

Особенности децентрализованных систем контроля версий
------------------------------------------------------------------------------------------

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

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

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

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

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

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

Знакомство с Bazaar-ом
=================

При установке Bazaar-а в систему устанавливается новая команда **bzr**. Всё остальное - подкоманды. Вы можете получить помощь с помощью bzr help. Некоторые аргименты группируются по темам. Наберите bzr help topics и увидите, какие темы доступны.

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

1. Установка адреса электронной почты через bzr whoami. Это самый простой способ.

Для установки глобальной идентификации используется::

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

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

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

#. Установка адреса электронной почты в ~/.bazaar/bazaar.conf [1]_ при помощи
добавки следующих строк. Пожалуйста учитывайте, что [DEFAULT] чувствителен к регистру букв::

[DEFAULT]
email=Your Name <email@isp.com>

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

[/the/path/to/the/branch]
email=Your Name <email@isp.com>

#. Переопределение двух предыдущих опций можно произвести установкой глобальных переменных среды $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 скрывает "не интересующие" Вас файлы, которые либо не изменялись, либо игнорируются.

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.. # everything since r1000
% bzr diff -r 1000..1100 # changes from 1000 to 1100

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

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

Фиксирование изменений
=================

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

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

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

::

% bzr commit -m "added my first file"

Выборочная фиксация изменений (commit)
----------------

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

% bzr commit -m "documentation fix" commit.py

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

% bzr commit .

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

Если Вы хотите отказаться от сделанных изменений, используйте команду **revert**, для возврата к предыдущей головной версии. Желательно перед этим использовать команду bzr diff, чтобы просмотреть изменения которые будут удалены. По умолчанию команда revert отменяет изменения целиком по всему дереву. Если передать ей файл или директорию, то команда применяется только к нему. Команда revert также очищает список ревизий ожидающих слияния.

Игнорируемые файлы
==============

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

Этот файл содержит список файлов, по одному на строку. Допускается использование групповых символов (для задания группы файлов, например, *.tmp - все файлы с расширением tmp). Типичное содержиоме файла выглядит так::

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

./config.h
doc/*.html

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

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

% bzr add .bzrignore
% bzr commit -m "Add ignore patterns"

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

bzr log
-------

Команда bzr log выводит список ревизий в хронологическом порядке, таким образом, что самой верхней строчкой является самая последняя ревизия. Запущенная с параметром --forward 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 выводит некотрую суммарную информацию о рабочем дереве и истории ветки.

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

::

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

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

% bzr pull

::

% bzr merge URL

::

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

::

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

::

% cd NEWDIR
% bzr merge --uncommitted OLDDIR

Переведено на Нотабеноиде
http://notabenoid.org/book/164/1657

Переводчики: AlexIljin, Neronyatkin, master