1
.. Этот файл в формате ReStructuredText - он может быть отформатирован в HTML,
2
.. или текст. В будущем планируется выделять примеры команд и автоматически
5
.. Данный текст сначала был на Wiki
6
.. http://bazaar.canonical.com/IntroductionToBzr
7
.. но был перемещен в дерево исходного кода что бы синхронизироваться
8
.. с исходным кодом и возможно автоматически тестироваться.
14
Текущая версия для bzr-0.91, 2007-08
20
Если вы уже знакомы с распределенными системами контроля версий, то можете
21
сразу перейти к "Представляемся Bazaar". Если, с другой стороны, вы знакомы с
22
системами контроля версий, но не знакомы с распределенными системами, тогда
23
стоит начать с "Чем отличаются распределенные системы". Иначе, возьмите кофе
24
или чай, расположитесь поудобнее и продолжим чтение.
26
Назначение контроля версий
27
==========================
29
Есть шансы, что вы уже работали с какими-либо текстовыми данными -- исходниками
30
программ, Web-сайтами, или конфигурационными файлами с которыми имеют дело
31
администраторы систем Unix в /etc. Также есть хорошие шансы, что вы делали
32
ошибки, которые вызывали потом глубокое сожаление. Возможно вы удалили
33
конфигурационный файл для вашего почтового сервера, или повредили исходный код
34
любимого проекта. Не важно что конкретно случилось, но вы просто удалили важную
35
информацию которую вы безнадежно хотели бы вернуть. Если такое когда либо
36
случалось с вами, то вы возможно готовы для Bazaar.
38
Системы контроля версий, такие как Bazaar дают возможность отслеживать
39
изменения для каталога, который они изменяют в нечто более сложное, что
40
называется **ветка**. Ветка не только сохраняет то как каталог выглядит в
41
данный момент, но также как он выглядел в различные моменты в прошлом. Затем,
42
когда вы сделаете что-то, что бы вы не хотели делать, вы сможете восстановить
43
каталог в том виде как он выглядел в какой-то момент в прошлом.
45
Системы контроля версий дают пользователям возможность сохранять изменения на
46
ветке "фиксируя **ревизию**". Созданная ревизия фактически является сводкой
47
изменений, которые были сделаны с последнего момента когда дерево было
50
Эти ревизии имеют также и другое назначение. Например, можно комментировать
51
ревизии, записав, что значит данный набор изменений, через необязательную
52
запись в журнале. Реальные записи в журнале могут быть похожи на "Исправлен
53
Web-шаблон для закрытия таблицы" и "Добавлена поддержка SFTP. Исправлен #595"
55
Мы храним этот журнал, что бы позже, в случае каких-либо проблем с SFTP, можно
56
было определить когда могла произойти проблема.
58
Чем отличаются распределенные системы
59
-------------------------------------
61
Многие системы контроля версий хранят данные на серверах. Если кто-то хочет
62
работать с кодом, который хранится в системе тогда ему нужно установить
63
соединение с сервером и "создать рабочую копию" кода. При этом создается
64
каталог в котором можно менять файлы и затем фиксировать изменения. Клиент
65
системы затем соединяется с сервером системы и сохраняет изменения. Этот метод
66
известен как централизованная модель.
68
Централизованная модель может иметь некоторые недостатки. Централизованная
69
система требует наличия соединения с сервером для любых действий по контролю
70
версий. Это может быть проблематичным если сервер находится на другой машине в
71
интернете, а клиент - нет. Или, хуже, клиент **в** интернете, а сервер - нет.
73
Распределенные системы контроля версий обходят эту проблему сохраняя ветки на
74
той же машине на которой находится клиент. В случае с Bazaar, ветка находится в
75
том же самом месте, что и код хранящийся под контролем версий. Это позволяет
76
пользователю сохранять (**фиксировать**) изменения когда он захочет -- даже без
77
сетевого подключения. Пользователю нужен доступ к интернету только когда он
78
хочет получить доступ к чьей-либо ветке в другом месте.
80
Общее требование, что многие люди хотят отслеживать изменения для каталога,
81
такие как изменения файлов и изменения в подкаталогах. Отслеживать это
82
"руками" ужасный процесс, который со временем становится громоздким. До тех пор
83
пока вы не попробуете систему контроля версий, такую как Bazaar. Такие
84
инструменты автоматизируют процесс сохранения данных, создавая **ревизии**
85
дерева каталога когда пользователь запрашивает сделать это.
87
Системы контроля версий, такие как Bazaar, могут делать намного больше чем
88
просто хранить изменения и отменять ошибочные действия. Например, с помощью
89
Bazaar разработчики могут взять изменения кода на одной ветке и объединить их
90
со связанной веткой -- даже если эти изменения хранятся на ветке которую создал
91
кто-то другой. Это позволяет разработчикам сотрудничать без необходимости
92
открывать доступ на запись к репозиторию.
94
Bazaar помнит ''предков'' ревизии: предыдущие ревизии на которых основана
95
текущая ревизия. Одна ревизия может иметь больше одного прямого потомка, каждый
96
из которых со своими изменениями, что представляет дивергенцию в эволюции
97
дерева. Создание веток в Bazaar позволяет нескольким людям сотрудничать в
98
эволюции проекта, без необходимости работать жестко по шагам. Создание веток
99
может быть полезным даже для одного разработчика.
101
Представляемся Bazaar
102
=====================
104
Bazaar устанавливает единственную новую команду, **bzr**. Все возможности
105
предоставляются через под-команды этой команды. Вы можете просмотреть краткую
106
справку командой ``bzr help``. Некоторые идеи группируются по темам,
107
используйте ``bzr help topics`` для списка доступных тем.
109
Одна из функций системы контроля версий -- отслеживать кто сделал изменения. В
110
распределенных системах для этого требуется идентифицировать каждого автора
111
уникально в глобальном плане. Большинство людей уже имеют такой идентификатор:
112
email адрес. Bazaar достаточно умен, что бы автоматически создавать email адрес
113
из текущего имени и адреса хоста. Если вам не нравится предположение которое
114
делает Bazaar вы сможете выбрать из трех опций:
116
#. Установить email адрес через ``bzr whoami``. Это наиболее простой путь.
118
Что бы установить такой глобальный идентификатор, используйте::
120
% bzr whoami "Ваше Имя <email@example.com>"
122
Если вы хотите использовать разные адреса для разных веток, то зайдите
123
в каталог с веткой и используйте::
125
% bzr whoami --branch "Ваше Имя <email@example.com>"
127
#. Установить email адрес в ``~/.bazaar/bazaar.conf`` [1]_, добавив следующие
128
строчки. Заметьте, что ``[DEFAULT]`` зависит от регистра символов::
131
email=Ваше Имя <email@isp.com>
133
Как и выше вы можете переопределить эти установки для каждой ветки
134
создав секцию для ветки в ``~/.bazaar/locations.conf`` и добавив
138
email=Ваше Имя <email@isp.com>
140
#. Переопределить два предыдущих способа, установив ваш полный email адрес в
141
глобальную переменную среды ``$BZR_EMAIL``, или ``$EMAIL`` (``$BZR_EMAIL``
142
имеет больший приоритет).
144
.. [1] Для Windows пользовательские файлы конфигурации могут быть найдены в
145
каталоге с данными приложений. Таким образом вместо
146
``~/.bazaar/branch.conf`` конфигурация может быть найдена в:
147
``C:\Documents and Settings\<пользователь>\Application Data\Bazaar\2.0\branch.conf``. Там же могут
148
быть найдены ``locations.conf``, ``ignore`` и каталог ``plugins``.
153
История по-умолчанию хранится на ветке в каталоге .bzr. В будущих версиях
154
Bazaar будут средства для хранения истории в отдельном репозитории, который
155
также сможет быть удаленным.
157
Мы создаем новую ветку выполнив ``bzr init`` в уже созданном каталоге::
164
/home/mbp/work/bzr.test/tutorial
171
Как и в CVS здесь три класса файлов: неизвестные, игнорируемые и под контролем
172
версий. Команда **add** ставит файл под контроль версий, т.е. изменения в нем
173
будут записываться системой::
175
% echo 'hello world' > hello.txt
185
Если вы добавили не тот файл просто сделайте ``bzr remove``, что бы сделать его
186
опять неизвестным. Рабочая копия файла не будет удалена в этом случае, хотя она
187
может быть удалена в других случаях [2]_.
189
.. [2] ``bzr remove`` удалит рабочую копию если она находится под контролем
190
версий, но не имеет изменений с последней зафиксированной версии. Вы
191
можете оставить файл указав опцию ``--keep`` для ``bzr remove``, или
192
удалить с опцией ``--force``.
197
Вся история хранится на ветке, которая является всего лишь каталогом на диске
198
содержащим файлы управления. По-умолчанию здесь нет отдельного репозитория, или
199
базы данных как в svn, или svk. По желанию вы можете создать репозиторий (см.
200
команду ``bzr init-repo``). Это можно сделать в случае очень больших веток, или
201
большого количества веток для проекта среднего размера.
203
Мы обычно обращаемся к веткам на нашем компьютере просто передав имя каталога
204
содержащего ветку. bzr также поддерживает доступ к веткам через http и sftp,
207
% bzr log http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
208
% bzr log sftp://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/
210
Установив для bzr плагины можно также осуществлять доступ к веткам с
211
использованием rsync.
213
Смотрите секцию `Публикация ветки`_ что бы получить больше информации о том как
214
поместить свою ветку в нужное место.
219
Как только вы закончили свою работу, вы захотите **зафиксировать** ее в истории
220
ревизий. Хорошая практика фиксировать изменения достаточно часто: когда
221
заработала новая функциональность, исправлена ошибка, или улучшен код, или
222
документация. При этом стоит проверить, что код компилируется и проходит все
223
тесты перед фиксацией, что бы быть уверенным, что каждая ревизия в хорошем
224
состоянии. Также можно просмотреть свои изменения, для уверенности, что вы
225
фиксируете именно то, что хотели и получить шанс проверить свою работу перед
226
тем как записать ее постоянно.
228
Две команды bzr особенно полезны здесь: **status** и **diff**.
233
Команда **status** показывает какие изменения были сделаны в рабочем каталоге
234
с момента последней ревизии::
240
``bzr status`` скрывает "неинтересные" файлы которые, либо не менялись, либо
241
игнорируются. Также команде status могут быть переданы необязательные имена
242
файлов, или каталогов для проверки.
247
Команда **diff** показывает изменения в тексте файлов в стандартном формате
248
diff. Вывод этой команды может быть передан другим командам, таким как
249
''patch'', ''diffstat'', ''filterdiff'' и ''colordiff''::
252
=== added file 'hello.txt'
253
--- hello.txt 1970-01-01 00:00:00 +0000
254
+++ hello.txt 2005-10-18 14:23:29 +0000
258
С опцией ``-r`` дерево файлов сравнивается с ранней ревизией, или показываются
259
изменения между двумя ревизиями::
261
% bzr diff -r 1000.. # изменения начиная с r1000
262
% bzr diff -r 1000..1100 # изменения c 1000 до 1100
264
Опция ``--diff-options`` говорит bzr запустить внешнюю программу diff, передав
267
% bzr diff --diff-options --side-by-side foo
269
Некоторые проекты предпочитают показывать префиксы в начале текста изменений
270
для старых (old) и новых (new) файлов. Опция ``--prefix`` может быть
271
использована для установки такого префикса. Плюс к этому команда ``bzr diff
272
-p1`` выводит префиксы в форме которая подходит для команды ``patch -p1``.
277
Когда состояние рабочего дерева подходит для сохранения оно может быть
278
**зафиксировано** на ветке, что создаст новую ревизию содержащую снимок
284
Команде **commit** можно передать сообщение описывающее изменения в ревизии.
285
Она также записывает идентификатор пользователя, текущее время и временную
286
зону, плюс список измененных файлов и их содержимого. Сообщение описывающее
287
изменения определяется через опцию ``-m``, или ``--message``. Можно также
288
вводить сообщения состоящие из нескольких строк; в большинстве оболочек вы
289
можете сделать это оставив открытую кавычку в конце строки.
293
% bzr commit -m "добавлен первый файл"
295
Также можно использовать опцию ``-F``, для получения сообщения из файла.
296
Некоторые люди делают заметки изменений во время работы над ними, а затем
297
просматривают изменения, что бы быть уверенными, что они сделали то, что хотели
298
сделать. (Этот файл может быть также полезен когда вы возвращаетесь к своей
299
работе после перерыва.)
301
Сообщение из текстового редактора
302
=================================
304
Если вы не используете опции ``-m`` и ``-F`` тогда bzr откроет текстовый
305
редактор для ввода сообщения. Какой редактор запускать может быть настроено
306
через переменные среды ``$VISUAL``, или ``$EDITOR``, которые могут быть
307
переопределены опцией ``editor`` в файле ``~/.bazaar/bazaar.conf``; опция
308
``$BZR_EDITOR`` переопределяет все описанные выше настройки. Если вы выходите
309
из редактора без каких-либо изменений, то фиксация будет прервана.
311
Файл который открывается в редакторе содержит горизонтальную линию. Часть файла
312
ниже этой линии включена только для информации и не будет частью сообщения об
313
изменениях. Ниже линии показывается список файлов которые были изменены. Для
314
создания сообщения вам надо написать свое сообщение выше линии, сохранить его и
317
Если вы хотите увидеть изменения содержимого файлов которые будут
318
зафиксированы, при редактировании сообщения вам нужно указать опцию
319
``--show-diff`` для команды ``commit``. Эта опция добавит изменения в файл
320
который будет открыт в редакторе ниже линии и списка измененных файлов. Это
321
значит, что вы можете читать изменения при редактировании сообщения, но они не
322
будут включены в сообщение когда вы закончите редактировать. Если вы хотите,
323
что бы части изменений были включены в сообщение вы можете скопировать и
324
вставить их выше ограничительной линии.
329
Если вы передадите список имен файлов, или каталогов после команды commit, то
330
будут зафиксированы только изменения для переданных объектов. Например::
332
% bzr commit -m "исправления документации" commit.py
334
По умолчанию bzr всегда фиксирует все изменения для дерева, даже если запущен
335
из подкаталога. Что бы зафиксировать только изменения от текущего каталога
336
и ниже, используйте::
341
Удаление не зафиксированных изменений
342
=====================================
344
Если вы сделали какие-либо изменения и не хотите оставлять их, используйте
345
команду **revert**, что бы вернутся к состоянию предыдущей ревизии. Хорошая
346
идея, использовать сначала ``bzr diff`` для просмотра изменений. По умолчанию
347
команда revert отменяет изменения на всем дереве, но если ей переданы имена
348
файлов, или каталогов то будут затронуты только они. ``bzr revert`` также
349
очищает список ревизий ожидающих объединения.
354
Многие деревья с исходным кодом содержат файлы которые не нужно хранить под
355
контролем версий, например резервные файлы текстового редактора, объектные
356
файлы и собранные программы. Вы можете просто не добавлять их, но они всегда
357
будут обнаруживаться как неизвестные. Вы также можете сказать bzr игнорировать
358
их добавив их в файл ``.bzrignore`` в корне рабочего дерева.
360
Этот файл содержит список шаблонов файлов, по одному в каждой строчке. Обычное
361
содержимое может быть таким::
368
Если шаблон содержит слеш, то он будет сопоставлен с полным путем начиная от
369
корня рабочего дерева; иначе он сопоставляется только с именем файла. Таким
370
образом пример выше игнорирует файлы с расширением ``.o`` во всех
371
подкаталогах, но пример ниже игнорирует только ``config.h`` в корне рабочего
372
дерева и HTML файлы в каталоге ``doc/``::
377
Для получения списка файлов которые игнорируются и соответствующих им шаблонов
378
используйте команду ``bzr ignored``::
384
Нет проблем если шаблон для игнорирования подходит для файла под контролем
385
версий, или вы добавили файл который игнорируется. Шаблоны не имеют никакого
386
эффекта на файлы под контролем версий, они только определяют показываются
387
неизвестные файлы, или просто игнорируются.
389
Файл ``.bzrignore`` обычно должен быть под контролем версий, что бы новые копии
390
ветки видели такие же шаблоны::
393
% bzr commit -m "Добавлены шаблоны для игнорирования"
396
Глобальные шаблоны для игнорирования
397
------------------------------------
399
Обычно есть файлы которые нужно игнорировать и они не специфичны для отдельных
400
проектов, а скорее специфичны для пользователя. Например, временные файлы
401
текстового редактора, или персональные временные файлы. Вместо того, что бы
402
добавлять их для игнорирования в каждом проекте, bzr поддерживает глобальный
403
файл игнорирования ``~/.bazaar/ignore`` [1]_. Он имеет такой же синтаксис, что
404
и файл игнорирования для каждого проекта.
413
Команда ``bzr log`` показывает список предыдущих ревизий. Команда ``bzr log
414
--forward`` делает тоже самое, но в хронологическом порядке, показывая более
415
поздние ревизии в конце.
417
Как и ``bzr diff``, ``bzr log`` поддерживает опцию ``-r``::
419
% bzr log -r 1000.. # Ревизия 1000 и все после нее
420
% bzr log -r ..1000 # Все до и включая r1000
421
% bzr log -r 1000..1100 # изменения с 1000 до 1100
422
% bzr log -r 1000 # Изменения только для ревизии 1000
428
Команда ``bzr info`` показывает суммарную информацию о рабочем дереве и истории
432
Каталоги под контролем версий
433
=============================
435
bzr может контролировать файлы и каталоги, отслеживая переименования и
436
упрощая их последующее объединение::
439
% echo 'int main() {}' > src/simple.c
452
Вы можете удалить файл, или каталог из под контроля версий просто удалив их
453
из рабочего каталога. Это немного отличается от CVS, которая требует что бы вы
454
также сделали ``cvs remove``.
456
``bzr remove`` удаляет файл из под контроля версий, но может и не удалять
457
рабочую копию файла [2]_. Это удобно когда вы добавили не тот файл, или решили,
458
что файл на самом деле не должен быть под контролем версий.
463
% bzr remove -v hello.txt
473
Если вы вдруг удалили не тот файл, то вы можете использовать ``bzr revert`` что
480
Часто вместо того что бы начинать свой собственный проект, вы хотите предложить
481
изменения для уже готового проекта. Что бы сделать это вам нужно получить копию
482
готовой ветки. Так как эта копия может быть потенциальной новой веткой эта
483
команда называется **branch**::
485
% bzr branch lp:bzr bzr.dev
488
Эта команда копирует полную историю ветки и после этого вы можете делать все
489
операции с ней локально: просматривать журнал, создавать и объединять другие
490
ветки. Здесь также есть опция для получения только части истории если это
493
Копию другой ветки можно также получить просто скопировав ее каталог,
494
развернув архив, или скопировав удаленно через такую утилиту как rsync.
497
Следование за изменениями основного проекта
498
===========================================
500
Вы можете обновлять свою ветку из родительской через получение ее изменений::
504
После этого локальный каталог будет копией родительского. Это включает и
505
''историю ревизий'' - список изменений сделанных на родительской ветке, а не
506
объединенных с других веток.
508
Эта команда работает только если локальная ветка, либо более старая копия
509
родительской ветки без новых фиксаций, либо все последние фиксации уже были
510
объединены с родительской веткой.
512
Объединение со связанных веток
513
==============================
515
Если две ветки разошлись (обе имеют уникальные изменения) тогда ``bzr merge`` -
516
это подходящая команда для использования. Объединение автоматически вычислит
517
изменения которые существуют на объединяемой ветке и отсутствуют в локальной
518
ветке и попытается объединить их с локальной веткой.
524
В случае конфликта при объединении будут созданы три файла с одними именем, но
525
разными расширениями. Файл с общими изменениями будет с расширением ".BASE",
526
файл с локальными изменениями будет с расширением ".THIS" и файл с изменениями
527
из объединяемой ветки будет с расширением ".OTHER". Используя такую программу
528
как kdiff3 вы теперь сможете достаточно легко объединить их в один файл. Для
529
фиксации изменений вам нужно переименовать объединенный файл (".THIS") в файл с
530
оригинальным именем. И для завершения исправления конфликта нужно использовать
531
команду resolve, которая удалит файлы ".OTHER" и ".BASE". Команда commit будет
532
выдавать ошибку пока существует один из файлов с расширением .BASE, .THIS, или
537
% kdiff3 file.BASE file.OTHER file.THIS
541
[**TODO**: описать маркеры конфликтов внутри файлов]
547
Для публикации ветки bzr вам не нужен специализированный сервер, нужен просто
548
обычный Web-сервер. Просто перенесите файлы на ваш сервер, включая каталог
549
.bzr. Можно опубликовать ветку (или изменения на ветке) одним из следующих трех
552
* Лучший способ - использовать для этого сам bzr.
556
% bzr push sftp://servername.com/path/to/directory
558
(Каталог назначения должна быть создан заранее, если только не указана
559
опция ``--create-prefix``)
561
* Другой способ - плагин ``rspush`` который включен в BzrTools и использует
562
rsync для публикации изменений в истории ревизий и рабочем дереве.
564
* Вы также можете скопировать файлы руками, переслав архив, или используя
565
rsync, или другой метод пересылки. Обычно это менее безопасно чем
566
использовать команду ``push``, но может быть быстрее и проще в каких-то
569
Перемещение изменений между деревьями
570
=====================================
572
Это случается и с лучшими из нас: в какой-то момент вы делаете изменения не в
573
том дереве файлов. Возможно потому, что вы случайно начали работать не в том
574
каталоге, либо изменений оказались больше чем вы ожидали и вы решили создать
577
Для перемещения изменений из одного дерева в другое используйте
582
% bzr merge --uncommitted OLDDIR
584
Эта команда перенесет все не зафиксированные изменения с ветки OLDDIR на ветку
585
NEWDIR. Команда не будет переносить зафиксированные изменения, даже если они
586
могли бы быть объединены с NEWDIR обычным объединением. Изменения также
587
остаются и в OLDDIR, но вы можете использовать ``bzr revert OLDDIR`` для их
588
удаления, как-то только убедитесь, что с NEWDIR все нормально.
590
NEWDIR не обязательно должен быть копией OLDDIR, но они должны быть связанными
591
ветками. Чем больше они отличаются, тем больше шанс возникновения конфликтов.
added
removed
doc/ru/tutorials/tutorial.txt
