Введение

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

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

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

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

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

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

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

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

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

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

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

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

   % bzr whoami "Ваше Имя <[email protected]>"

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

   % bzr whoami --branch "Ваше Имя <[email protected]>"

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

   [DEFAULT]
   email=Ваше Имя <[email protected]>

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

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

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

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

История по-умолчанию хранится на ветке в каталоге .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].

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

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

% 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

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

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

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

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

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

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

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

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

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

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

% 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 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, но они должны быть связанными ветками. Чем больше они отличаются, тем больше шанс возникновения конфликтов.