Управление версиями в Subversion

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

Рассматриваемую ситуацию иллюстрирует Рисунок 1.2, «Проблема потери изменений». Допустим, у нас есть два соразработчика — Гарри и Салли. Каждый из них решил одновременно отредактировать один и тот же файл из хранилища. Если первым свои изменения в хранилище сохранит Гарри, то возможно, что (несколькими минутами позже) Салли может непреднамеренно перезаписать их своей новой версией файла. Несмотря на то, что версия файла Гарри не будет полностью потеряна (так как система помнит каждое изменение), внесенные Гарри изменения не будут отражены в новой версии файла Салли, потому что, начиная, она не видела изменения Гарри. Работа Гарри фактически потеряна — или, по крайней мере, отсутствует в последней версии файла — по случайности. Как раз этой ситуации мы и хотим избежать!

Рисунок 1.2. Проблема потери изменений

Для того, чтобы несколько авторов не мешало работать друг другу, многие системы управления версиями применяют модель блокирование-изменение-разблокирование. Эта модель запрещает одновременное редактирование файла несколькими пользователями. Эксклюзивность доступа гарантируется блокировками. Перед началом редактирования Гарри должен «заблокировать» файл. Если Гарри заблокирует файл, Салли уже не сможет его заблокировать и внести свои изменения. Ей остается только читать файл и ждать, пока Гарри закончит свои изменения и снимет блокировку. Лишь после того, как Гарри разблокирует файл, Салли сможет получить его, заблокировать и начать редактирование. Рисунок 1.3, «Модель блокирование-изменение-разблокирование» демонстрирует это простое решение.

Рисунок 1.3. Модель блокирование-изменение-разблокирование

Проблемой модели блокирование-изменение-разблокирование является то, что она немного ограниченная и часто доставляет неудобства пользователям:

Subversion, CVS и ряд других систем управления версиями в качестве альтернативы блокированию пользуются моделью копирование-изменение-слияние. В этой модели каждый пользовательский клиент связывается с хранилищем проекта и создает персональную рабочую копию — локальное отражение файлов и каталогов хранилища. После этого пользователи работают одновременно и независимо друг от друга, изменяя свои личные копии. В конце концов, личные копии сливаются в новую, итоговую версию. Обычно система управления версиями помогает в слиянии, но, разумеется, за его корректное выполнение отвечает человек.

В качестве примера предположим, что Гарри и Салли создали рабочие копии одного и того же проекта, скопировав их из хранилища. Они работают одновременно и в своих рабочих копиях вносят изменения в один и тот же файл А. Первой свои изменения в хранилище сохраняет Салли. Когда позже Гарри попытается сохранить свои изменения, хранилище проинформирует его о том, что его файл А устарел. Другими словами, файл А каким то образом изменился со времени, когда он его последний раз копировал. Поэтому Гарри просит свой клиент слить любые изменения из хранилища в его рабочую копию файла А. По счастливому совпадению, изменения Салли не перекрываются с его собственными; после объединения обоих наборов изменений он сохраняет свою рабочую копию обратно в хранилище. Рисунок 1.4, «Модель копирование-изменение-слияние» и Рисунок 1.5, «Модель копирование-изменение-слияние (продолжение)» показывают этот процесс.

Рисунок 1.4. Модель копирование-изменение-слияние

Рисунок 1.5. Модель копирование-изменение-слияние (продолжение)

А что будет, если изменения Салли перекрывают изменения Гарри? Что тогда? Эта ситуация называется конфликтом и, как правило, это не является большой проблемой. Когда Гарри просит свой клиент слить последние изменения из хранилища в рабочую копию, его копия файла А помечается некоторым образом как находящаяся в состоянии конфликта: у него будет возможность видеть оба набора конфликтующих изменений и вручную сделать между ними выбор. Помните, что ПО не может автоматически разрешать конфликты; только человек способен к пониманию и выполнению осмысленного выбора. Разрешив вручную перекрывающиеся изменения — возможно, после обсуждения с Салли — он может безопасно сохранить объединенный файл обратно в хранилище.

Модель копирование-изменение-слияние может выглядеть немного хаотично, однако, на практике она отлично работает. Пользователи могут работать параллельно, не тратя время на ожидание друг друга. При работе над одними и теми же файлами оказывается, что большинство параллельно вносимых изменений совсем не перекрываются; конфликты бывают редко. И время, которое было потрачено на разрешение конфликтов, как правило, значительно меньше времени, отнимаемого блокирующей системой.

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

В книге для идентификации файлов и директорий в хранилище Subversion применяются URL. В основном, в этих URL используются стандартные правила записи, позволяющие указывать имя сервера и номер порта как часть URL:

$ svn checkout http://svn.example.com:9834/repos
…

Однако, в обработке URL системой Subversion есть некоторые нюансы, о которых нужно помнить. Например, в соответствии с принятыми соглашениями, URL, использующий метод доступа file: (этот метод доступа используется для локальных хранилищ), должен либо включать имя сервера localhost, либо вообще не содержать имени сервера:

$ svn checkout file:///path/to/repos
…
$ svn checkout file://localhost/path/to/repos
…

Кроме того, тем, кто применяет схему file: на платформе Windows, необходимо использовать неофициальные «стандартные» правила записи при обращении к хранилищу, которое находится на одном компьютере, но на разных дисках с клиентом. Обе приведенные ниже записи будут работать; здесь X — это имя диска, на котором находится хранилище:

C:\> svn checkout file:///X:/path/to/repos
…
C:\> svn checkout "file:///X|/path/to/repos"
…

При второй форме записи для того, чтобы вертикальная черта не расценивалась как канал, необходимо взять URL в кавычки. Также обратите внимание на использование в URL прямого слеша, несмотря на то, что родная (не-URL) форма записи пути в Windows использует обратный слеш.

Ну и наконец, нужно сказать о том, что клиент Subversion при необходимости автоматически кодирует URL точно так же, как это делает веб-браузер. Например, если URL будет содержать пробел или ASCII-символы в верхнем регистре:

$ svn checkout "http://host/path with space/project/españa"

…то Subversion скроет небезопасные символы и будет вести себя так, как будто вы напечатали:

$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a

Если в URL есть пробелы, возьмите его в кавычки, и тогда командная оболочка обработает это все как один аргумент программы svn.

Вы уже читали о рабочих копиях; теперь мы покажем как клиент Subversion создает и использует их.

Рабочая копия Subversion представляет собой обычное дерево каталогов на вашем компьютере, содержащее набор файлов. Вы можете по своему усмотрению редактировать эти файлы и, если это исходные коды, вы можете обычным способом скомпилировать из них программу. Ваша рабочая копия — это ваше личное рабочее пространство. Subversion как не смешивает с вашими изменения, вносимые другими, так и не делает доступными для других изменения, сделанные вами, пока вы сами не прикажете сделать это. Вы даже можете иметь несколько рабочих копий одного и того же проекта.

После того, как вы внесли изменения в файлы вашей рабочей копии и убедились в том, что они корректно работают, Subversion предлагает вам команды «публикации» (записи в хранилище) ваших изменений, в результате чего они станут доступными для всех участников проекта. Если другие участники проекта опубликовали свои изменения, Subversion предлагает вам команды для объединения (путем чтения информации из хранилища) этих изменений с вашей рабочей копией.

Рабочая копия содержит несколько дополнительных файлов, созданных и обслуживаемых Subversion, которые помогают ей при выполнении этих команд. В частности, каждый каталог в вашей рабочей копии содержит подкаталог с именем .svn который называется служебным каталогом рабочей копии. Файлы в служебном каталоге помогают Subversion определить какие файлы рабочей копии содержат неопубликованные изменения, и какие файлы устарели по отношению к файлам других участников.

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

Например, предположим, что у вас есть хранилище, содержащее два программных проекта: paint и calc. Каждый проект располагается в своем собственном каталоге как показано на Рисунок 1.6, «Файловая система хранилища».

Рисунок 1.6. Файловая система хранилища

Для того, чтобы создать рабочую копию, вам нужно получить какой-либо из подкаталогов хранилища. (Возможно, термин получить звучит как что-то, связанное с блокированием или резервированием ресурсов, но это не так; данная команда просто создает для вас личную копию проекта.) Например, если вы получите /calc, у вас будет рабочая копия наподобие этой:

$ svn checkout http://svn.example.com/repos/calc
A    calc/Makefile
A    calc/integer.c
A    calc/button.c
Checked out revision 56.

$ ls -A calc
Makefile  integer.c  button.c  .svn/

Буквы А говорят о том, что Subversion добавил этот элемент в вашу рабочую копию. Теперь у вас есть личная копия каталога /calc хранилища, с одним небольшим добавлением — каталогом .svn, содержащим, как было указано выше, дополнительную информацию, необходимую Subversion.

Предположим, вы внесли изменения в button.c. Так как каталог .svn помнит дату изменения файла и его оригинальное содержимое, Subversion может сказать о том, что вы изменили файл. Subversion не публикует ваших изменений, пока вы не прикажете это сделать. Публикация ваших изменений более известна как фиксация (или checking in) изменений в хранилище.

Для того, чтобы опубликовать ваши изменения, вы можете воспользоваться командой commit.

$ svn commit button.c -m "Fixed a typo in button.c."
Sending        button.c
Transmitting file data .
Committed revision 57.

Теперь ваши изменения в button.c, вместе с примечанием, описывающим эти изменения (а именно: исправление опечатки), зафиксированы в хранилище; если другой пользователь создаст рабочую копию /calc, он увидит ваши изменения в последней версии файла.

Предположим, у вас есть партнер, Салли, которая создала рабочую копию /calc одновременно с вами. Когда вы зафиксировали изменения в button.c, рабочая копия Салли осталась неизмененной, так как Subversion модифицирует рабочие копии только по запросу пользователей.

Для приведения рабочей копии в актуальное состояние Салли может попросить Subversion обновить её рабочую копию, используя команду Subversion update. Это включит ваши изменения в ее рабочую копию, так же как и все другие изменения, зафиксированные после того, как она создавала рабочую копию.

$ pwd
/home/sally/calc

$ ls -A
.svn/ Makefile integer.c button.c

$ svn update
U    button.c
Updated to revision 57.

Вывод команды svn update говорит, что Subversion обновила содержимое button.c. Обратите внимание, что Салли не должна указывать, какой файл обновить; для определения файлов, которые необходимо привести в актуальное состояние, Subversion использует информацию в каталоге .svn, а также информацию из хранилища.

Операция svn commit публикует изменения любого количества файлов и каталогов за одну атомарную операцию. В своей рабочей копии вы можете менять содержимое файлов, создавать, удалять, переименовывать и копировать файлы и каталоги, а затем зафиксировать все изменения за одну атомарную транзакцию.

Под «атомарной транзакцией» понимается следующее: либо в хранилище вносятся все изменения полностью, либо они не вносятся вообще. Subversion ведёт себя так, принимая в расчет возможные программные сбои, системные сбои, проблемы с сетью, а также неверные действия пользователя.

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

Рисунок 1.7, «Хранилище» отлично иллюстрирует хранилище. Представьте массив номеров правок, начинающийся с 0, с направлением слева направо. Каждый номер правки имеет соответствующее дерево файлов, а каждое дерево представляет собой «снимок» того, как хранилище выглядело после фиксации.

Рисунок 1.7. Хранилище

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

calc/Makefile:4
     integer.c:4
     button.c:4

На данный момент рабочий каталог полностью соответствует правке 4 в хранилище. Допустим, что вы внесли изменения в button.c и зафиксировали эти изменения. При отсутствии других фиксаций ваша фиксация создаст правку под номером 5, и теперь ваша рабочая копия выглядит следующим образом:

calc/Makefile:4
     integer.c:4
     button.c:5

Предположим, что после этого Салли фиксирует изменения integer.c, создавая правку 6. Если вы воспользуетесь svn update для приведения своей рабочей копии в актуальное состояние, то она станет выглядеть так:

calc/Makefile:6
     integer.c:6
     button.c:6

Изменения, внесенные Салли в integer.c будут отражены в вашей рабочей копии, и ваши изменения в button.c также будут присутствовать. В этом примере текст Makefile в правках 4, 5 и 6 идентичен, однако Subversion проставляет номер правки 6 для вашей рабочей копии Makefile, чтобы показать что файл не устарел. Таким образом, после того как вы выполните полное обновление вашей рабочей копии, она будет полностью соответствовать текущему состоянию хранилища.

В служебном каталоге .svn/ для каждого файла рабочего каталога Subversion записывает информацию о двух важнейших свойствах:

Используя эту информацию при соединении с хранилищем, Subversion может сказать, в каком из следующих четырех состояний находится рабочий файл:

Может показаться, что следить за актуальным состоянием рабочей копии сложно. Это не так. Для того, чтобы узнать состояние любого элемента в вашей рабочей копии, существует команда svn status. За более подробной информацией об этой команде обратитесь к «svn status».

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

При командной работе над проектом обновление рабочей копии необходимо для получения любых изменений, внесенных другими разработчиками проекта с момента вашего последнего обновления. Используйте svn update для синхронизации вашей рабочей копии с последней правкой в хранилище.

$ svn update
U  foo.c
U  bar.c
Updated to revision 2.

В данном случае, кто-то другой зафиксировал изменения в файлах foo.c и bar.c после вашего последнего обновления, и Subversion обновила вашу рабочую копию, включив эти изменения.

Рассмотрим поподробнее информацию, выводимую командой svn update. Когда сервер отправляет изменения в вашу рабочую копию, для каждого элемента выводится латинская буква — код, определяющий действие, выполненное Subversion для приведения вашей рабочей копии в актуальное состояние:

Теперь вы можете приступать к делу и вносить изменения в рабочую копию. Как правило, целесообразнее всего работать отдельно по каждому частному изменению (или набору изменений), такому как реализация новой функциональной возможности, исправление ошибки и т. п. Здесь вы будете пользоваться такими командами Subversion как svn add, svn delete, svn copy и svn move. Однако, если вы просто редактируете файлы, которые уже находятся под контролем Subversion, ни одна из этих команд вам не нужна. В своей рабочей копии вы можете делать следующие изменения:

Для внесения изменений в файлы используйте свой текстовый редактор, текстовый процессор, графическую программу или любой другой инструмент, который вы обычно используете. Subversion обрабатывает бинарные файлы так же легко как и текстовые — и настолько же эффективно.

Рассмотрим четыре подкоманды Subversion, которые вы чаще всего будете использовать при внесении изменений в структуру (команды svn import и svn mkdir мы рассмотрим позже).

	Внимание
	Хотя вы можете редактировать файлы любыми программными средствами, не следует менять структуру рабочей копии, не проинформировав о своих действиях Subversion. Для изменения структуры рабочей копии используйте команды svn copy, svn delete и svn move, а для добавления новых файлов и каталогов под контроль версий используйте svn add.

После внесения изменений вы должны зафиксировать их в хранилище, но перед этим было бы неплохо посмотреть, что же, собственно, вы изменили. Проанализировав перед фиксацией свои изменения, вы сможете составить более аккуратное лог-сообщение. Кроме того, вы можете обнаружить, что изменили файл непреднамеренно, что позволит еще до фиксации вернуть файл к предыдущему состоянию. К тому же, это хорошая возможность пересмотреть и проверить изменения перед их публикацией. Чтобы увидеть все сделанные изменения, вы можете воспользоваться svn status, svn diff и svn revert. Первые две команды вы можете использовать для того, чтобы найти измененные файлы рабочей копии, а затем, при помощи третьей, отменить некоторые (или все) изменения.

Subversion была оптимизирована для решения такой задачи и способна выполнять множество действий без обращения к хранилищу. В частности, рабочая копия содержит в .svn-области скрытую кэшированую «нетронутую» копию каждого версионированного файла. За счет этого Subversion может быстро показать, как изменились ваши рабочие файлы или даже предоставить, не связываясь с хранилищем, возможность откатить изменения.

  L     some_dir            # svn оставила блокировку в .svn-области для some_dir
M       bar.c               # содержимое bar.c имеет локальные изменения
 M      baz.c               # в baz.c есть изменения в свойствах, а в содержимом нет
X       3rd_party           # каталог является частью внешней зависимости
?       foo.o               # svn не управляет foo.o
!       some_dir            # svn управляет этим элементом, но он отсутствует или поврежден
~       qux                 # элемент версионировался как файл/каталог/ссылка, но тип был изменен
I       .screenrc           # svn не управляет этим элементом и настроена на его игнорирование
A  +    moved_dir           # добавлен с историей своего происхождения
M  +    moved_dir/README    # добавлен с историей и имеет локальные изменения
D       stuff/fish.c        # файл запланирован для удаления
A       stuff/loot/bloo.h   # файл запланирован для добавления
C       stuff/loot/lump.c   # файл имеет текстовый конфликт с момента обновления
 C      stuff/loot/glub.c   # файл имеет конфликт в свойствах с момента обновления
R       xyz.c               # файл запланирован для замены
    S   stuff/squawk        # файл или каталог были переключены на ветку
     K  dog.jpg             # файл заблокирован локально; присутствует маркер блокирования
     O  cat.jpg             # файл заблокирован в хранилище другим пользователем
     B  bird.jpg            # файл заблокирован локально, но блокировка была нарушена
     T  fish.jpg            # файл заблокирован локально, но блокировка была снята

$ svn status stuff/fish.c
D      stuff/fish.c

$ svn status --verbose
M               44        23    sally     README
                44        30    sally     INSTALL
M               44        20    harry     bar.c
                44        18    ira       stuff
                44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
                44        21    sally     stuff/things
A                0         ?     ?        stuff/things/bloo.h
                44        36    harry     stuff/things/gloo.c

$ svn status --show-updates --verbose
M      *        44        23    sally     README
M               44        20    harry     bar.c
       *        44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
A                0         ?     ?        stuff/things/bloo.h
Status against revision:   46

$ svn diff
Index: bar.c
===================================================================
--- bar.c (revision 3)
+++ bar.c (working copy)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>

 int main(void) {
-  printf("Sixty-four slices of American Cheese...\n");
+  printf("Sixty-five slices of American Cheese...\n");
 return 0;
 }

Index: README
===================================================================
--- README  (revision 3)
+++ README  (working copy)
@@ -193,3 +193,4 @@
+Note to self:  pick up laundry.

Index: stuff/fish.c
===================================================================
--- stuff/fish.c  (revision 1)
+++ stuff/fish.c  (working copy)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.

Index: stuff/things/bloo.h
===================================================================
--- stuff/things/bloo.h (revision 8)
+++ stuff/things/bloo.h (working copy)
+Here is a new file to describe
+things about bloo.

$ svn diff > patchfile

svn revert

Теперь предположим, что, просмотрев вывод команды diff, вы обнаружили, что изменения в README ошибочны — к примеру, потому, что в своем редакторе вы случайно набрали текст, предназначавшийся для другого файла.

В такой ситуации как нельзя кстати окажется команда svn revert.

$ svn revert README
Reverted 'README'

Subversion возвращает файл в состояние, предшествующее модификации, путем замены файла его кэшированной «первоначальной» копией из .svn-области. Кроме того, обратите внимание, что svn revert может отменить любые запланированные операции — например, вы можете прийти к решению всё-таки не добавлять новый файл:

$ svn status foo
?      foo

$ svn add foo
A         foo

$ svn revert foo
Reverted 'foo'

$ svn status foo
?      foo

	Замечание
	svn revert ITEM будет иметь точно такой же эффект, как и удаление ITEM из вашей рабочей копии, а затем выполнение svn update -r BASE ITEM. Однако, если вы отменяете изменения для файла, svn revert будет иметь одно значительное отличие — для восстановления файла не происходит соединения с хранилищем.

Или, допустим, вы ошибочно удалили файл из-под контроля версий:

$ svn status README
       README

$ svn delete README
D         README

$ svn revert README
Reverted 'README'

$ svn status README
       README

Мы уже видели, как svn status -u может предупредить о конфликтах. Предположим, вы запустили svn update и увидели кое-что интересное:

$ svn update
U  INSTALL
G  README
C  bar.c
Updated to revision 46.

Коды U и G интереса не представляют; эти файлы без проблем поглотили изменения из хранилища. Файлы, отмеченные U, локальных изменений не содержат и были Updated — обновлены изменениями из хранилища. Отмеченные G были merGed — слиты, это значит, что файл имел локальные изменения, но изменения, пришедшие из хранилища, не перекрываются с локальными изменениями.

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

Всякий раз, когда возникает конфликт, в его обнаружении и разрешении вам, как правило, помогают три вещи:

Например, Салли внесла изменения в файл sandwich.txt из хранилища. Одновременно Гарри изменил файл в своей рабочей копии и зафиксировал его. Салли обновляет свою рабочую копию перед фиксацией и получает конфликт:

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2

Теперь Subversion не позволит зафиксировать файл sandwich.txt, пока не будут удалены три временных файла.

$ svn commit --message "Add a few more things"
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict

Для разрешения конфликта у вас есть три варианта:

После разрешения конфликта вам нужно известить об этом Subversion, выполнив svn resolved. Эта команда удалит три временных файла, и Subversion больше не будет считать, что файл находится в состоянии конфликта. ^[10]

$ svn resolved sandwich.txt
Resolved conflicted state of 'sandwich.txt'

$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard
Bottom piece of bread

<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======

=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2

Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Creole Mustard
Bottom piece of bread

$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls sandwich.*
sandwich.txt  sandwich.txt.mine  sandwich.txt.r2  sandwich.txt.r1
$ cp sandwich.txt.r2 sandwich.txt
$ svn resolved sandwich.txt

$ svn revert sandwich.txt
Reverted 'sandwich.txt'
$ ls sandwich.*
sandwich.txt

Наконец-то! Вы закончили с редактированием, слили все изменения с сервера и готовы к тому, чтобы зафиксировать их в хранилище.

Команда svn commit отправляет все ваши изменения в хранилище. При фиксации изменений необходимо описать ваши изменения в тексте лог-сообщения. Лог-сообщение будет присоединено к созданной правке. Если ваше лог-сообщение короткое, вы можете указать его в командной строке, используя опцию --message (или -m):

$ svn commit --message "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.

Однако, если вы заранее составляли лог-сообщение в процессе работы, можно попросить Subversion взять его из файла, передав имя этого файла в параметре --file:

$ svn commit --file logmsg
Sending        sandwich.txt
Transmitting file data .
Committed revision 4.

Если вы не укажете ни опции --message, ни опции --file, для составления лог сообщения Subversion автоматически запустит ваш любимый редактор (см. editor-cmd в разделе «Config»).

	Подсказка
	Если, набирая сообщение в редакторе, вы решите отменить фиксацию, то можете просто выйти из редактора без сохранения изменений. Если вы уже сохранили сообщение, просто удалите текст и выполните сохранение еще раз. $ svn commit Waiting for Emacs...Done Log message unchanged or not specified a)bort, c)ontinue, e)dit a $

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

$ svn commit --message "Add another rule"
Sending        rules.txt
svn: Commit failed (details follow):
svn: Out of date: 'rules.txt' in transaction 'g'

В таком случае вам нужно выполнить svn update, разобраться со всеми слияниями и конфликтами и попытаться выполнить фиксацию снова.

Мы рассмотрели простейший рабочий цикл использования Subversion. В Subversion существует много других возможностей, которые вы можете применять для управления рабочей копией и хранилищем; но очень многое можно сделать, используя исключительно команды, рассмотренные в этой главе.

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

$ svn log
------------------------------------------------------------------------
r3 | sally | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line

Added include lines and corrected # of cheese slices.
------------------------------------------------------------------------
r2 | harry | Mon, 15 Jul 2002 17:47:57 -0500 | 1 line

Added main() methods.
------------------------------------------------------------------------
r1 | sally | Mon, 15 Jul 2002 17:40:08 -0500 | 1 line

Initial import
------------------------------------------------------------------------

Обратите внимание на то, что по умолчанию лог сообщения выводятся в обратном хронологическом порядке. Если вам нужно увидеть другой диапазон правок в заранее определенном порядке или только одну правку, укажите параметр --revision (-r):

$ svn log --revision 5:19    # shows logs 5 through 19 in chronological order

$ svn log -r 19:5            # shows logs 5 through 19 in reverse order

$ svn log -r 8               # shows log for revision 8

Кроме того, можно проанализировать историю лог-сообщений отдельного файла или каталога. Например:

$ svn log foo.c
…
$ svn log http://foo.com/svn/trunk/code/foo.c
…

В результате будут показаны лог-сообщения только для тех правок, в которых изменялся рабочий файл (или URL).

Если вам нужно еще больше информации о файле или каталоге, то для svn log есть параметр --verbose (-v). Так как Subversion позволяет перемещать и копировать файлы и каталоги, важно отслеживать изменения путей в файловой системе. Поэтому в режиме расширенного вывода svn log включает перечень измененных в правке путей:

$ svn log -r 8 -v
------------------------------------------------------------------------
r8 | sally | 2002-07-14 08:15:29 -0500 | 1 line
Changed paths:
M /trunk/code/foo.c
M /trunk/code/bar.h
A /trunk/code/doc/README

Frozzled the sub-space winch.

------------------------------------------------------------------------

Кроме того, svn log имеет параметр --quiet (-q), сокращающий лог сообщение. При его объединении с --verbose выдаются только имена измененных файлов.

$ svn log -r 2
------------------------------------------------------------------------
$

Ранее мы уже познакомились с svn diff — эта команда показывает различия файла в едином формате представления различий; она используется для того, что бы показать локальные изменения, внесенные в рабочую копию, перед их фиксацией в хранилище.

Вообще, существует три возможных варианта использования svn diff:

$ svn diff
Index: rules.txt
===================================================================
--- rules.txt (revision 3)
+++ rules.txt (working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$

$ svn diff --revision 3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt (revision 3)
+++ rules.txt (working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$

$ svn diff --revision 2:3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt (revision 2)
+++ rules.txt (revision 3)
@@ -1,4 +1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
+Freedom = Responsibility
 Everything in moderation
 Chew with your mouth open
$

$ svn diff --revision 4:5 http://svn.red-bean.com/repos/example/trunk/text/rules.txt
…
$

Если вы хотите проанализировать ранние версии файла, а не различия между двумя файлами, можно воспользоваться svn cat:

$ svn cat --revision 2 rules.txt
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
Chew with your mouth open
$

Или вы можете перенаправить вывод прямо в файл:

$ svn cat --revision 2 rules.txt > rules.txt.v2
$

Наверное, вам интересно, почему для замены файла старой правкой мы не воспользовались svn update --revision. Есть несколько причин, по которым нам оказалось предпочтительнее воспользоваться svn cat.

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

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

Команда svn list показывает содержимое каталога в хранилище, при этом не закачивая его на локальную машину:

$ svn list http://svn.collab.net/repos/svn
README
branches/
clients/
tags/
trunk/

Если вам нужна более подробная информация, воспользуйтесь флагом --verbose (-v), и вы увидете что-то подобное:

$ svn list --verbose http://svn.collab.net/repos/svn
   2755 harry          1331 Jul 28 02:07 README
   2773 sally               Jul 29 15:07 branches/
   2769 sally               Jul 29 12:07 clients/
   2698 harry               Jul 24 18:07 tags/
   2785 sally               Jul 29 19:07 trunk/

Колонки показывают правку, в которой файл или каталог последний раз изменялись, имя пользователя, вносившего изменения, размер (если это файл), дату последнего изменения и имя элемента.

В дополнение ко всем упомянутым выше командам, можно воспользоваться svn update и svn checkout с параметром --revision, чтобы переместить рабочую копию «назад во времени»^[12]:

$ svn checkout --revision 1729 # Checks out a new working copy at r1729
…
$ svn update --revision 1729 # Updates an existing working copy to r1729
…

Когда Subversion изменяет рабочую копию (или любую информацию в области .svn), она пытается делать это как можно более осторожно. Перед изменением рабочей копии Subversion записывает свои намерения в лог-файл. Затем для выполнения запрошенных изменений она выполняет команды из лог-файла, устанавливая блокировку той части рабочей копии, с которой работает — это делается для предотвращения работы других Subversion-клиентов с той рабочей копией, которая находится в промежуточном состоянии. После выполнения запрошеных действий Subversion удаляет лог файл. Архитектурно это напоминает журналируемую файловую систему. Если работа Subversion была прервана (в результате того, что процесс был убит или, например, из-за машинного сбоя), лог файлы остаются на диске. Перезапустив выполнение лог файлов, Subversion может завершить предварительно начатые операции, и рабочая копия снова вернется в согласованное состояние.

Именно это, собственно, и делает svn cleanup: она ищет в рабочей копии и выполняет незавершенные лог-файлы, удаляя по ходу выполнения блокировки в рабочей копии. Если Subversion когда-нибудь говорила вам о том, что часть рабочей копии «заблокирована», то вам нужно запустить эту команду. Кроме того, svn status покажет для заблокированных элементов букву L:

$ svn status
  L    somedir
M      somedir/foo.c

$ svn cleanup
$ svn status
M      somedir/foo.c

Не путайте эти блокировки рабочей копии с обычными блокировками, которые устанавливают пользователи Subversion, использующие модель конкурентного управления версиями «блокировка-изменение-разблокировка»; за более подробным определением обратитесь к Three meanings of «lock»

Команда svn import — это быстрый способ скопировать неверсионированное дерево файлов в хранилище, cоздавая при необходимости подкаталоги.

$ svnadmin create /usr/local/svn/newrepos
$ svn import mytree file:///usr/local/svn/newrepos/some/project \
             -m "Initial import"
Adding         mytree/foo.c
Adding         mytree/bar.c
Adding         mytree/subdir
Adding         mytree/subdir/quux.h

Committed revision 1.

В предыдущем примере выполняется копирование содержимого каталога mytree в каталог some/project хранилища:

$ svn list file:///usr/local/svn/newrepos/some/project
bar.c
foo.c
subdir/

Обратите внимание на то, что после завершения импорта оригинальное дерево файлов не конвертируется в рабочую копию. Чтобы начать работать, вам необходимо создать новую рабочую копию (svn checkout) дерева файлов.

Клиент Subversion понимает ряд ключевых слов. Эти ключевые слова можно использовать вместо целочисленных аргументов опции --revision, при этом Subversion переведет их в конкретные номера правок:

Из данного описания можно сделать очевидный вывод о том, что ключевые слова PREV, BASE, и COMMITTED могут использоваться только при ссылках на пути в рабочей копии; они не применимы к URL-адресам хранилища. Напротив, ключевое слово HEAD можно использовать совместно с обоими типами путей.

Ниже приведено несколько примеров использования ключевых слов правок:

$ svn diff --revision PREV:COMMITTED foo.c

# показать последнее изменение, зафиксированное для foo.c

$ svn log --revision HEAD

# показать лог-сообщение для последней фиксации в хранилище

$ svn diff --revision HEAD

# сравнить ваш рабочий файл (с учетом локальных изменений)
# с последней правкой в хранилище

$ svn diff --revision BASE:HEAD foo.c

# сравнить ваш «исходный» foo.c (без учета локальных
# изменений) с последней версией в хранилище

$ svn log --revision BASE:HEAD

# показать все логи фиксаций со времени вашего последнего обновления

$ svn update --revision PREV foo.c

# отменить последние изменения в foo.c, понизив рабочую правку foo.c
      
$ svn diff -r BASE:14 foo.c

# сравнить неизмененную версию foo.c и версию foo.c в правке 14

Номера правок не несут никакой информации об окружающем мире за пределами системы управления версиями, тогда как вам иногда требуется сопоставить момент времени в реальной жизни с моментом в истории версий. Чтобы помочь вам в этом, опция --revision допускает указание даты, которую заключают в фигурные скобки ({ и }). Subversion принимает дату и время в формате, соответствующем стандарту ISO-8601, а также в некоторых других. Ниже приведено несколько примеров. (Не забывайте брать в кавычки любые даты, содержащие пробелы.)

$ svn checkout -r {2006-02-17}
$ svn checkout -r {15:30}
$ svn checkout -r {15:30:00.200000}
$ svn checkout -r {"2006-02-17 15:30"}
$ svn checkout -r {"2006-02-17 15:30 +0230"}
$ svn checkout -r {2006-02-17T15:30}
$ svn checkout -r {2006-02-17T15:30Z}
$ svn checkout -r {2006-02-17T15:30-04:00}
$ svn checkout -r {20060217T1530}
$ svn checkout -r {20060217T1530Z}
$ svn checkout -r {20060217T1530-0500}
…

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

$ svn log -r {2006-11-28}
------------------------------------------------------------------------
r12 | ira | 2006-11-27 12:31:51 -0600 (Mon, 27 Nov 2006) | 6 lines
…

Также вы можете задавать диапазоны дат. Subversion найдет все правки между обеими датами включительно:

$ svn log -r {2006-11-20}:{2006-11-29}
…

	Внимание
	Временные метки правок сохраняются как их неверсионированные изменяемые свойства (см. «Свойства» ). Исходя из этого, изменением временных меток можно легко исказить истинную хронологию, или даже удалить совсем информацию о времени правки. Это может привести к неожиданным результатам при внутреннем преобразовании дат в номера правок, выполняемом Subversion.

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

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

Эту задачу можно решить с помощью обычных файлов. Рядом, в одном каталоге, вы можете иметь файлы image123.jpg и image123-thumbnail.jpg. Если важно сохранить оригинальное имя файла, миниатюры могут размещаться в отдельном каталоге (например, thumbnails/image123.jpg). Таким же образом, отдельно от основного графического файла, можно хранить описание и дату. Проблема заключается в том, что файловая структура будет сильно разрастаться при каждом добавлении фотографии на сайт.

Теперь представим, как можно организовать работу того же веб-сайта, используя Subversion-свойства файлов. Допустим, имеется файл image123.jpg и у этого файла установлены свойства caption, datestamp и даже thumbnail. В этом случае рабочая копия выглядит гораздо нагляднее. Фактически, она выглядит так, как будто содержит только сами графические файлы, и ничего больше. Однако ваши скрипты автоматизации знают, что с помощью svn (а еще лучше языковой обвязки Subversion — см. «Using Languages Other than C and C++») можно получить дополнительную, необходимую для показа на сайте информацию, не занимаясь чтением индексного файла или манипуляциями с путями.

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

Issue(s): IZ2376, IZ1919
Reviewed by:  sally

This fixes a nasty segfault in the wort frabbing process
…

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

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
property 'copyright' set on 'calc/button.c'
$

Однако мы уже знаем о том, насколько гибкими могут быть свойства Subversion. И если вам необходимо задать свойству многострочное текстовое или даже бинарное значение, передавать его через командную строку будет неудобно. Для таких случаев команда propset имеет параметр --file (-F), позволяющий указать имя файла с новым значением свойства.

$ svn propset license -F /path/to/LICENSE calc/button.c
property 'license' set on 'calc/button.c'
$

На имена свойств накладывается ряд ограничений. Имя должно начинаться с буквы, двоеточия (:) или подчеркивания (_); после них можно использовать цифры, тире (-) и точки (.). ^[13]

Кроме команды propset, svn предлагает команду propedit. Эта команда использует для добавления или изменения свойства заданную программу-редактор (см. «Config»). При выполнении команды svn вызывает редактор с временным файлом, содержащим текущее значение свойства (или с пустым файлом, если добавляется новое свойство). Затем вы просто изменяете в редакторе значение, пока оно не станет таким, каким вы хотели бы его видеть, сохраняете временный файл и выходите из редактора. Если Subversion обнаружит, что вы действительно изменили существующее значение свойства, будет записано новое значение. Если вы вышли из редактора, не внеся никаких изменений, модификации свойства не произойдет.

$ svn propedit copyright calc/button.c  ### exit the editor without changes
No changes to property 'copyright' on 'calc/button.c'
$

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

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
property 'copyright' set on 'calc/Makefile'
property 'copyright' set on 'calc/button.c'
property 'copyright' set on 'calc/integer.c'
…
$

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

$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software

Существует даже вариант команды proplist, перечисляющий как имена, так и значения свойств. Нужно просто добавить параметр --verbose (-v).

$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
  license : ================================================================
Copyright (c) 2006 Red-Bean Software.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the recipe for Fitz's famous
red-beans-and-rice.
…

Последняя команда, относящаяся к свойствам — propdel. Несмотря на то, что Subversion позволяет сохранять свойства с пустыми значениями, полностью удалить свойство с помощью propedit или propset нельзя. Например, такая команда не даст желаемого эффекта:

$ svn propset license '' calc/button.c
property 'license' set on 'calc/button.c'
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
  license :
$

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

$ svn propdel license calc/button.c
property 'license' deleted from 'calc/button.c'.
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
$

Помните, мы говорили о неверсионированных свойствах правок? Их тоже можно изменять с помощью svn. Просто добавьте параметр командной строки --revprop и укажите правку, свойство которой вы хотите изменить. Поскольку правки глобальны, указывать пути не требуется до тех пор, пока вы находитесь в рабочей копии того хранилища, свойство правки в котором вам нужно изменить. В противном случае, нужно просто указать URL любого пути в интересующем вас хранилище (в том числе это может быть и корневой URL хранилища). Например, вы можете заменить лог-сообщение фиксации в существующей правке. ^[14] Если текущий рабочий каталог является частью рабочей копии хранилища, можно просто выполнить команду svn propset, не указывая целевой путь:

$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
property 'svn:log' set on repository revision '11'
$

Но даже если вы не выгружали из хранилища рабочую копию, можно изменить свойство, указав корневой URL хранилища:

$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop \
              http://svn.example.com/repos/project
property 'svn:log' set on repository revision '11'
$

Обратите внимание на то, что изменение этих неверсионированных свойств должно быть явно разрешено администратором (см. «Hook Scripts»). Учитывая то, что свойства не версионируются, при неаккуратном редактировании вы рискуете потерять информацию. Чтобы предотвратить потерю информации, администратор хранилища может принять меры предосторожности, и по умолчанию изменение неверсионированных свойств запрещено.

Подсказка

Пользователям следует, по возможности, пользоваться svn propedit вместо svn propset. Хотя конечный результат обеих команд будет одинаков, первая позволит увидеть текущее значение свойства перед изменением, и таким образом удостовериться, что вносятся именно те изменения, которые были задуманы. В особенности это справедливо для модификации неверсионированных свойств правок. Да и изменять свойства с многострочными значениями гораздо проще в текстовом редакторе, а не в командной строке.

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

Так же как и в случае с содержимым файлов, изменения свойств являются локальной модификацией и становятся постоянными только при их фиксации в хранилище с помощью svn commit. Изменение свойств можно легко отменить — команда svn revert восстановит файлы и каталоги в их первоначальное состояние, включая содержимое, свойства и все остальное. Кроме того, интересную информацию о состоянии свойств файлов и каталогов можно получить с помощью команд svn status и svn diff.

$ svn status calc/button.c
 M     calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
   + (c) 2006 Red-Bean Software

$

Обратите внимание на то, что подкоманда status показала M не в первой, а во второй колонке. Это произошло потому, что в calc/button.c изменились свойства, а не текстовое содержимое. Если бы мы изменили и то и другое, в первой колонке также стояла бы буква M (см. «svn status»).

% svn update calc
M  calc/Makefile.in
 C calc/button.c
Updated to revision 143.
$

$ svn status calc
 C     calc/button.c
?      calc/button.c.prej
$ cat calc/button.c.prej
prop 'linecount': user set to '1256', but update set to '1301'.
$

Кроме того, нужно помнить о нестандартном подходе, используемом Subversion при выводе различий для свойств. Безусловно, можно запустить svn diff и перенаправить вывод для создания работоспособного патч-файла. Но программа patch будет просто игнорировать различия свойств — как правило, она игнорирует любой мусор, который не может обработать. К сожалению, это означает, что для полного применения патча, сгенерированного svn diff, изменения свойств придется вносить вручную.

Поддержка свойств — мощная функциональная особенность Subversion. Свойства служат базовым механизмом для реализации многих других функций Subversion, обсуждаемых в книге — поддержки текстового поиска различий и слияния, подстановки ключевых слов, трансляции символов перевода строки и т. д. Однако, чтобы получить реальную выгоду от свойств, их нужно задавать для соответствующих файлов и каталогов. К сожалению, среди повседневных забот об этом очень легко забыть, особенно учитывая то, что неустановка значения свойства обычно не приводит к явно заметным ошибкам (по сравнению, скажем, с недобавлением файла под версионный контроль). Чтобы помочь в установке свойств для нужных элементов, Subversion обеспечивает пару простых, но полезных функций.

При каждом добавлении файла под версионный контроль с помощью команд svn add или svn import Subversion пытается автоматически установить несколько базовых свойств файлов. Во-первых, в операционных системах, файловые системы которых поддерживают бит разрешения выполнения, Subversion автоматически задает свойство svn:executable для вновь добавленных или импортированных файлов, у которых этот бит установлен. (Обратитесь к «Исполнимость файла» за дополнительной информации об этом свойстве.) Во-вторых, Subversion выполняет очень простую эвристическую процедуру, чтобы определить, имеет ли файл читаемое содержимое. Если это не так, Subversion автоматически устанавливает свойство svn:mime-type этого файла в значение application/octet-stream (это базовый MIME-тип, обозначающий «набор байтов»). Конечно, если Subversion угадает тип файла неправильно, или если вы пожелаете присвоить свойству svn:mime-type более точное значение — например, image/png или application/x-shockwave-flash — вы всегда можете удалить или отредактировать это свойство. (За дополнительной информацией об использовании MIME-типов в Subversion обратитесь к «Тип содержимого файла».)

Через собственную систему конфигурирования среды исполнения (см. «Параметры времени выполнения») Subversion также поддерживает более гибкую возможность автоматической установки свойств, которая позволяет задавать соответствия между масками имен файлов и именами и значениями свойств. Еще раз: эти соответствия воздействуют на добавление и импорт, и могут не только переопределять решение о MIME-типе по умолчанию, принимаемое Subversion в ходе этих операций, но и устанавливать другие стандартные или пользовательские свойства. Например, вы могли бы задать соответствие, чтобы при каждом добавлении JPEG-файла — то есть элемента, соответствующего маске *.jpg — Subversion автоматически присваивал бы свойству svn:mime-type значение image/jpeg. Или, к примеру, для всех файлов, соответствующих маске *.cpp, свойство svn:eol-style устанавливалось бы в native, а svn:keywords — в Id. Поддержка автоматических свойств — это, пожалуй, наиболее удобный инструмент Subversion в части работы со свойствами среди всего набора доступных средств. См. «Config» для дополнительной информации о настройке такой поддержки.

Subversion принадлежит к многочисленному семейству приложений, распознающих и использующих для типизации содержимого многоцелевые расширения интернет-почты (Multipurpose Internet Mail Extensions — MIME). Свойство svn:mime-type не только является универсальным местом хранения информации о типе содержимого файла, но и определяет некоторые особенности поведения Subversion.

Например, одной из полезных возможностей Subversion является контекстное, построчное слияние изменений, полученных от сервера во время обновления, с рабочей копией. Однако, для файлов, не содержащих текстовых данных, как правило, не существует понятия «строки». Поэтому для версионированных файлов, чье свойство svn:mime-type указывает на нетекстовый MIME-тип (как правило, это все, что не начинается с text/, хотя есть несколько исключений), Subversion не будет пытаться провести контекстное слияние во время обновления. Вместо этого, каждый раз когда вы локально модифицируете рабочую копию бинарного файла, и выполняете после этого обновление, файл будет переименован с добавлением расширения .orig, после чего Subversion запишет под оригинальным именем новый файл рабочей копии, c изменениями, полученными в процессе обновления, но без ваших локальных исправлений. Такое поведение призвано защитить пользователя от неудачных попыток выполнить контекстное слияние для файлов, к которым его нельзя применить.

Кроме того, если для файла определено свойство svn:mime-type, Apache-модуль Subversion будет использовать его значение при формировании HTTP-заголовка Content-type: в ответ на GET-запросы. Благодаря этому ваш браузер (в том случае, если он будет использоваться для просмотра содержимого Subversion-хранилища) будет знать, как правильно отобразить этот файл.

На многих операционных системах возможность выполнения файла как команды определяется битом разрешения выполнения. Обычно по умолчанию этот бит не задан; он должен быть явно установлен пользователем для тех файлов, которым это необходимо. Однако, было бы слишком сложным запоминать, какие именно файлы в только что созданной рабочей копии должны иметь установленный бит выполнения, и устанавливать этот бит. Поэтому Subversion поддерживает свойство svn:executable, позволяющее указать, для каких файлов должен быть установлен бит исполнения. При создании рабочей копии Subversion самостоятельно установит этот бит для таких файлов.

Это свойство не оказывает никакого эффекта на файловых системах, не использующих бита разрешения выполнения, таких как FAT32 и NTFS. ^[16]. Кроме того, хотя значение этого свойства не задано, Subversion принудительно устанавливает ему значение *. Наконец, это свойство действительно только для файлов, но не для каталогов.

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

Сказанное означает, что по умолчанию Subversion не уделяет никакого внимания используемой в файлах разновидности маркера конца строки (EOL). К сожалению, различные операционные системы используют различные соглашения о том, какая последовательность символов означает конец текстовой строки в файле. Например, программы под Windows обычно используют в качестве признака конца строки последовательность из двух управляющих символов ASCII — возврата каретки (CR) и перевода строки (LF). В то же время программы под Unix для обозначения конца строки используют единственный символ LF.

Далеко не все програмы способны понимать файлы, в которых признак конца строки отличается по формату от принятого стиля завершения строк в данной операционной системе. Обычным делом является ситуация, когда программы под Unix рассматривают символ CR, присутствующий в файлах Windows, как обычный символ (часто представляя его как ^M), или когда программы под Windows слепляют все строки файла Unix в одну гигантскую строку, поскольку в нем отсутствуют комбинации символов возврата каретки и перевода строки (или CRLF), обозначающие концы строк.

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

Но на практике многие распространенные утилиты либо не умеют правильно считывать файлы с чужеродными EOL-маркерами, либо конвертируют концы строк в файле к родному стилю при сохранении файла. Если разработчик сталкивается с первым случаем, он оказывается вынужденным пользоваться внешними утилитами конвертации (такими как dos2unix или ее аналоги, unix2dos), чтобы подготовить файл к редактированию. Во втором случае дополнительная подготовка файлов не требуется. Однако, в обоих случаях получается файл, каждая строка в котором отличается от исходной! Прежде чем фиксировать свои изменения, пользователь может сделать одно из двух. Он может либо использовать утилиту конвертации, чтобы восстановить в модифицированном файле прежний стиль завершения строк; либо просто зафиксировать файл с новыми EOL-маркерами.

Результатом такого сценария станут напрасная трата времени и нежелательные изменения в фиксируемых файлах. Напрасная трата времени сама по себе обходится довольно дорого. А когда фиксация вносит изменения в каждую строку файла, становится невозможным определить, какие строки файла действительно изменились по существу. Был ли устранен тот самый баг? В какой строке имелась синтаксическая ошибка?

Данную проблему решает свойство svn:eol-style. Когда этому свойству задано одно из допустимых значений, Subversion использует его для того, чтобы определить вариант специальной обработки файла, производимой для того, чтобы стиль завершения строки не изменялся туда-сюда при каждой фиксации, выполняемой из другой операционной системы. Допустимы следующие значения:

In the Subversion repository, a lock is a piece of metadata which grants exclusive access to one user to change a file. This user is said to be the lock owner. Each lock also has a unique identifier, typically a long string of characters, known as the lock token. The repository manages locks, ultimately handling their creation, enforcement, and removal. If any commit transaction attempts to modify or delete a locked file (or delete one of the parent directories of the file), the repository will demand two pieces of information—that the client performing the commit be authenticated as the lock owner, and that the lock token has been provided as part of the commit process as a sort of proof that client knows which lock it is using.

To demonstrate lock creation, let's refer back to our example of multiple graphic designers working with on the same binary image files. Harry has decided to change a JPEG image. To prevent other people from committing changes to the file while he is modifying it (as well as alerting them that he is about to change it), he locks the file in the repository using the svn lock command.

$ svn lock banana.jpg --message "Editing file for tomorrow's release."
'banana.jpg' locked by user 'harry'.
$

There are a number of new things demonstrated in the previous example. First, notice that Harry passed the --message option to svn lock. Similar to svn commit, the svn lock command can take comments (either via --message (-m) or --file (-F)) to describe the reason for locking the file. Unlike svn commit, however, svn lock will not demand a message by launching your preferred text editor. Lock comments are optional, but still recommended to aid communication.

Secondly, the lock attempt succeeded. This means that the file wasn't already locked, and that Harry had the latest version of the file. If Harry's working copy of the file had been out-of-date, the repository would have rejected the request, forcing Harry to svn update and reattempt the locking command. The locking command would also have failed if the file already been locked by someone else.

As you can see, the svn lock command prints confirmation of the successful lock. At this point, the fact that the file is locked becomes apparent in the output of the svn status and svn info reporting subcommands.

$ svn status
     K banana.jpg

$ svn info banana.jpg
Path: banana.jpg
Name: banana.jpg
URL: http://svn.example.com/repos/project/banana.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 2198
Node Kind: file
Schedule: normal
Last Changed Author: frank
Last Changed Rev: 1950
Last Changed Date: 2006-03-15 12:43:04 -0600 (Wed, 15 Mar 2006)
Text Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Properties Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
Lock Owner: harry
Lock Created: 2006-06-14 17:20:31 -0500 (Wed, 14 Jun 2006)
Lock Comment (1 line):
Editing file for tomorrow's release.

$

That the svn info command, which does not contact the repository when run against working copy paths, can display the lock token reveals an important fact about lock tokens—that they are cached in the working copy. The presence of the lock token is critical. It gives the working copy authorization to make use of the lock later on. Also, the svn status command shows a K next to the file (short for locKed), indicating that the lock token is present.

Now that Harry has locked banana.jpg, Sally is unable to change or delete that file:

$ svn delete banana.jpg
D         banana.jpg
$ svn commit -m "Delete useless file."
Deleting       banana.jpg
svn: Commit failed (details follow):
svn: DELETE of
'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
423 Locked (http://svn.example.com)
$

But Harry, after touching up the banana's shade of yellow, is able to commit his changes to the file. That's because he authenticates as the lock owner, and also because his working copy holds the correct lock token:

$ svn status
M    K banana.jpg
$ svn commit -m "Make banana more yellow"
Sending        banana.jpg
Transmitting file data .
Committed revision 2201.
$ svn status
$

Notice that after the commit is finished, svn status shows that the lock token is no longer present in working copy. This is the standard behavior of svn commit—it searches the working copy (or list of targets, if you provide such a list) for local modifications, and sends all the lock tokens it encounters during this walk to the server as part of the commit transaction. After the commit completes successfully, all of the repository locks that were mentioned are released—even on files that weren't committed. This is meant to discourage users from being sloppy about locking, or from holding locks for too long. If Harry haphazardly locks thirty files in a directory named images because he's unsure of which files he needs to change, yet only only changes four of those file, when he runs svn commit images, the process will still release all thirty locks.

This behavior of automatically releasing locks can be overridden with the --no-unlock option to svn commit. This is best used for those times when you want to commit changes, but still plan to make more changes and thus need to retain existing locks. You can also make this your default behavior by setting the no-unlock runtime configuration option (see «Параметры времени выполнения»).

Of course, locking a file doesn't oblige one to commit a change to it. The lock can be released at any time with a simple svn unlock command:

$ svn unlock banana.c
'banana.c' unlocked.

When a commit fails due to someone else's locks, it's fairly easy to learn about them. The easiest of these is svn status --show-updates:

$ svn status --show-updates
M              23   bar.c
M    O         32   raisin.jpg
       *       72   foo.h
Status against revision:     105
$

In this example, Sally can see not only that her copy of foo.h is out-of-date, but that one of the two modified files she plans to commit is locked in the repository. The O symbol stands for «Other», meaning that a lock exists on the file, and was created by somebody else. If she were to attempt a commit, the lock on raisin.jpg would prevent it. Sally is left wondering who made the lock, when, and why. Once again, svn info has the answers:

$ svn info http://svn.example.com/repos/project/raisin.jpg
Path: raisin.jpg
Name: raisin.jpg
URL: http://svn.example.com/repos/project/raisin.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 105
Node Kind: file
Last Changed Author: sally
Last Changed Rev: 32
Last Changed Date: 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006)
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Lock Comment (1 line):
Need to make a quick tweak to this image.
$

Just as svn info can be used to examine objects in the working copy, it can also be used to examine objects in the repository. If the main argument to svn info is a working copy path, then all of the working copy's cached information is displayed; any mention of a lock means that the working copy is holding a lock token (if a file is locked by another user or in another working copy, svn info on a working copy path will show no lock information at all). If the main argument to svn info is a URL, then the information reflects the latest version of an object in the repository, and any mention of a lock describes the current lock on the object.

So in this particular example, Sally can see that Harry locked the file on February 16th to «make a quick tweak». It being June, she suspects that he probably forgot all about the lock. She might phone Harry to complain and ask him to release the lock. If he's unavailable, she might try to forcibly break the lock herself or ask an administrator to do so.

A repository lock isn't sacred—in Subversion's default configuration state, locks can be released not only by the person who created them, but by anyone at all. When somebody other than the original lock creator destroys a lock, we refer to this as breaking the lock.

From the administrator's chair, it's simple to break locks. The svnlook and svnadmin programs have the ability to display and remove locks directly from the repository. (For more information about these tools, see «An Administrator's Toolkit».)

$ svnadmin lslocks /usr/local/svn/repos
Path: /project2/images/banana.jpg
UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Owner: frank
Created: 2006-06-15 13:29:18 -0500 (Thu, 15 Jun 2006)
Expires:
Comment (1 line):
Still improving the yellow color.

Path: /project/raisin.jpg
UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Owner: harry
Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Expires:
Comment (1 line):
Need to make a quick tweak to this image.

$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
Removed lock on '/project/raisin.jpg'.
$

The more interesting option is allowing users to break each other's locks over the network. To do this, Sally simply needs to pass the --force to the unlock command:

$ svn status --show-updates
M              23   bar.c
M    O         32   raisin.jpg
       *       72   foo.h
Status against revision:     105
$ svn unlock raisin.jpg
svn: 'raisin.jpg' is not locked in this working copy
$ svn info raisin.jpg | grep URL
URL: http://svn.example.com/repos/project/raisin.jpg
$ svn unlock http://svn.example.com/repos/project/raisin.jpg
svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
'raisin.jpg' unlocked.
$

Now, Sally's initial attempt to unlock failed because she ran svn unlock directly on her working copy of the file, and no lock token was present. To remove the lock directly from the repository, she needs to pass a URL to svn unlock. Her first attempt to unlock the URL fails, because she can't authenticate as the lock owner (nor does she have the lock token). But when she passes --force, the authentication and authorization requirements are ignored, and the remote lock is broken.

Of course, simply breaking a lock may not be enough. In the running example, Sally may not only want to break Harry's long-forgotten lock, but re-lock the file for her own use. She can accomplish this by running svn unlock --force and then svn lock back-to-back, but there's a small chance that somebody else might lock the file between the two commands. The simpler thing to is steal the lock, which involves breaking and re-locking the file all in one atomic step. To do this, Sally passes the --force option to svn lock:

$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn lock --force raisin.jpg
'raisin.jpg' locked by user 'sally'.
$

In any case, whether the lock is broken or stolen, Harry may be in for a surprise. Harry's working copy still contains the original lock token, but that lock no longer exists. The lock token is said to be defunct. The lock represented by the lock-token has either been broken (no longer in the repository), or stolen (replaced with a different lock). Either way, Harry can see this by asking svn status to contact the repository:

$ svn status
     K raisin.jpg
$ svn status --show-updates
     B         32   raisin.jpg
$ svn update
  B  raisin.jpg
$ svn status
$

If the repository lock was broken, then svn status --show-updates displays a B (Broken) symbol next to the file. If a new lock exists in place of the old one, then a T (sTolen) symbol is shown. Finally, svn update notices any defunct lock tokens and removes them from the working copy.

We've seen how svn lock and svn unlock can be used to create, release, break, and steal locks. This satisfies the goal of serializing commit access to a file. But what about the larger problem of preventing wasted time?

For example, suppose Harry locks an image file and then begins editing it. Meanwhile, miles away, Sally wants to do the same thing. She doesn't think to run svn status --show-updates, so she has no idea that Harry has already locked the file. She spends hours editing the file, and when she tries to commit her change, she discovers that either the file is locked or that she's out-of-date. Regardless, her changes aren't mergeable with Harry's. One of these two people has to throw away their work, and a lot of time has been wasted.

Subversion's solution to this problem is to provide a mechanism to remind users that a file ought to be locked before the editing begins. The mechanism is a special property, svn:needs-lock. If that property is attached to a file (regardless of its value, which is irrelevant), then Subversion will try to use filesystem-level permissions to make the file read-only, unless, of course, the user has explicitly locked the file. When a lock-token is present (as a result of running svn lock), the file becomes read-write. When the lock is released, the file becomes read-only again.

The theory, then, is that if the image file has this property attached, then Sally would immediately notice something is strange when she opens the file for editing. Many applications alert users immediately when a read-only file is opened for editing. And nearly all applications would at least prevent her from saving changes to the file. This reminds her to lock the file before editing, whereby she discovers the pre-existing lock:

$ /usr/local/bin/gimp raisin.jpg
gimp: error: file is read-only!
$ ls -l raisin.jpg
-r--r--r--   1 sally   sally   215589 Jun  8 19:23 raisin.jpg
$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-06-08 07:29:18 -0500 (Thu, 08 June 2006)
Lock Comment (1 line):
Making some tweaks.  Locking for the next two hours.
$

	Подсказка
	Users and administrators alike are encouraged to attach the svn:needs-lock property to any file which cannot be contextually merged. This is the primary technique for encouraging good locking habits and preventing wasted effort.

Note that this property is a communication tool which works independently from the locking system. In other words, any file can be locked, whether or not this property is present. And conversely, the presence of this property doesn't make the repository require a lock when committing.

Unfortunately, the system isn't flawless. It's possible that even when a file has the property, the read-only reminder won't always work. Sometimes applications misbehave and «hijack» the read-only file, silently allowing users to edit and save the file anyway. There's not much that Subversion can do in this situation—at the end of the day, there's simply no substitution for good interpersonal communication. ^[21]

Создать ветку очень просто — при помощи команды svn copy в хранилище создается копия проекта. Subversion может копировать не только отдельные файлы, но и целые каталоги. Итак, вам нужно сделать копию каталога /calc/trunk. Где должна лежать эта новая копия? Где угодно — этот вопрос определяется правилами проекта. Допустим, что по правилам вашей команды ветки создаются в каталоге /calc/branches хранилища, и вы хотите назвать свою ветку my-calc-branch. Тогда вам следует создать новый каталог /calc/branches/my-calc-branch, который будет копией /calc/trunk.

Копию можно создать двумя различными способами. Сперва мы покажем более длинный способ, просто для того, что бы пояснить суть идеи. Для начала создадим рабочую копию корневого каталога проекта /calc:

$ svn checkout http://svn.example.com/repos/calc bigwc
A  bigwc/trunk/
A  bigwc/trunk/Makefile
A  bigwc/trunk/integer.c
A  bigwc/trunk/button.c
A  bigwc/branches/
Checked out revision 340.

Теперь, чтобы создать копию, достаточно просто передать два пути в пределах рабочей копии команде svn copy:

$ cd bigwc
$ svn copy trunk branches/my-calc-branch
$ svn status
A  +   branches/my-calc-branch

В результате команда svn copy рекурсивно копирует рабочий каталог trunk в новый рабочий каталог branches/my-calc-branch. Теперь команда svn status покажет, что новый каталог запланирован для добавления в хранилище. Обратите внимание на знак «+» после буквы А. Он означает, что запланированное для добавления представляет собой какую-то копию, а не что-то новое. При следующей фиксации Subversion создаст в хранилище каталог /calc/branches/my-calc-branch, скопировав его из /calc/trunk вместо того, чтобы повторно отправлять по сети всю информацию рабочей копии:

$ svn commit -m "Creating a private branch of /calc/trunk."
Adding         branches/my-calc-branch
Committed revision 341.

А теперь покажем простой способ создания ветки, о котором мы упоминали раньше: команда svn copy может оперировать двумя URL-адресами напрямую.

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Creating a private branch of /calc/trunk."

Committed revision 341.

В сущности, между этими двумя методами нет разницы. Оба варианта создают в правке 341 новый каталог, и этой новый каталог является копией /calc/trunk. Это показывает Рисунок 4.3, «Хранилище, содержащее новую копию». Обратите внимание на то, что второй метод, кроме всего прочего, выполняет немедленную фиксацию. ^[24]Эта процедура более проста в использовании, так как нет необходимости в выгрузке в рабочую копию значительного объема данных из хранилища. По сути, в этом случае можно вовсе не иметь рабочей копии.

Рисунок 4.3. Хранилище, содержащее новую копию

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

$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch
A  my-calc-branch/Makefile
A  my-calc-branch/integer.c
A  my-calc-branch/button.c
Checked out revision 341.

В этой рабочей копии нет ничего особенного; это просто зеркало другого каталога хранилища. Однако, если Салли обновит свою рабочую копию, она не увидит там ваших изменений. Рабочая копия Салли создана из каталога /calc/trunk. (Смотрите далее в этой главе раздел «Переключение рабочей копии»: команда svn switch является альтернативным способом создания рабочей копии ветки.)

Предположим, что за неделю были сделаны следующие фиксации:

Теперь у файла integer.c есть два независимых направления разработки, что демонстрирует Рисунок 4.4, «История ветвления для одного файла».

Рисунок 4.4. История ветвления для одного файла

Если посмотреть историю изменений, сделанных в вашей копии integer.c, можно увидеть интересные вещи:

$ pwd
/home/user/my-calc-branch

$ svn log --verbose integer.c
------------------------------------------------------------------------
r343 | user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/branches/my-calc-branch/integer.c

* integer.c:  frozzled the wazjub.

------------------------------------------------------------------------
r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   A /calc/branches/my-calc-branch (from /calc/trunk:340)

Creating a private branch of /calc/trunk.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Обратите внимание на то, что Subversion полностью прослеживает всю историю ветки integer.c во времени, в том числе пересекая точку создания копии. Создание ветки показано как событие в истории, потому что файл integer.c был неявно скопирован при копировании всего каталога /calc/trunk/. Теперь давайте посмотрим, какой результат выдаст такая же команда для Салли:

$ pwd
/home/sally/calc

$ svn log --verbose integer.c
------------------------------------------------------------------------
r344 | sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  fix a bunch of spelling errors.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Салли увидит свои собственные изменения в правке 344, а ваши, сделанные в правке 343 — нет. Subversion позаботилась о том, чтобы эти две фиксации затронули разные файлы, имеющие разное расположение в хранилище. Тем не менее, Subversion будет показывать то, что два файла имеют общую историю. До создания ветки-копии в правке 341 это был один файл. Поэтому и вы, и Салли видите изменения, сделанные в правках 303 и 98.

Из этого раздела вы должны запомнить две вещи.

В предыдущем разделе мы отметили, что и вы, и Салли, одновременно, в разных ветках вносите изменения в файл integer.c. Если посмотреть на лог-сообщение Салли для правки 344, вы увидите, что она исправила несколько орфографических ошибок. Конечно же, в вашей копии этого файла эти ошибки остались. Не исключено, что ваши будущие изменения этого файла коснутся областей, содержащих эти орфографические ошибки, и таким образом вы получите несколько потенциальных конфликтов при последующем объединении вашей ветки. Поэтому лучше получить изменения от Салли сейчас, до того, как вы начнете вплотную работать с этой частью файла.

Настал момент воспользоваться командой svn merge. Эта команда, оказывается, является очень близким родственником команды svn diff (о которой вы читали в Глава 2, Экскурсия по Subversion). Обе команды способны сравнивать любые два объекта в хранилище и показывать различия. Например, вы можете попросить svn diff показать все изменения, сделанные Салли в правке 344:

$ svn diff -r 343:344 http://svn.example.com/repos/calc/trunk

Index: integer.c
===================================================================
--- integer.c (revision 343)
+++ integer.c (revision 344)
@@ -147,7 +147,7 @@
     case 6:  sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
     case 7:  sprintf(info->operating_system, "Macintosh"); break;
     case 8:  sprintf(info->operating_system, "Z-System"); break;
-    case 9:  sprintf(info->operating_system, "CPM"); break;
+    case 9:  sprintf(info->operating_system, "CP/M"); break;
     case 10:  sprintf(info->operating_system, "TOPS-20"); break;
     case 11:  sprintf(info->operating_system, "NTFS (Windows NT)"); break;
     case 12:  sprintf(info->operating_system, "QDOS"); break;
@@ -164,7 +164,7 @@
     low = (unsigned short) read_byte(gzfile);  /* read LSB */
     high = (unsigned short) read_byte(gzfile); /* read MSB */
     high = high << 8;  /* interpret MSB correctly */
-    total = low + high; /* add them togethe for correct total */
+    total = low + high; /* add them together for correct total */

     info->extra_header = (unsigned char *) my_malloc(total);
     fread(info->extra_header, total, 1, gzfile);
@@ -241,7 +241,7 @@
      Store the offset with ftell() ! */

   if ((info->data_offset = ftell(gzfile))== -1) {
-    printf("error: ftell() retturned -1.\n");
+    printf("error: ftell() returned -1.\n");
     exit(1);
   }

@@ -249,7 +249,7 @@
   printf("I believe start of compressed data is %u\n", info->data_offset);
   #endif

-  /* Set postion eight bytes from the end of the file. */
+  /* Set position eight bytes from the end of the file. */

   if (fseek(gzfile, -8, SEEK_END)) {
     printf("error: fseek() returned non-zero\n");

Команда svn merge ведет себя практически идентично. Но вместо вывода различий на терминал она применяет их к рабочей копии в виде локальных изменений:

$ svn merge -r 343:344 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

Вывод команды svn merge показывает, что к вашей копии integer.c был применен патч. Теперь она содержит изменения Салли — они были «скопированы» из главной линии разработки в вашу рабочую копию, вашу собственную ветку, и теперь существуют в виде локальных изменений. С этого момента вы можете просмотреть локальные изменения и убедиться в том, что они корректны.

Возможна ситуация, когда не все будет так хорошо и integer.c окажется в состоянии конфликта. Тогда вам будет необходимо разрешить конфликт обычным путем (см. Глава 2, Экскурсия по Subversion), либо, если вы придете к мнению, что объединение было плохой идеей, просто отказаться от него, отменив локальные изменения командой svn revert.

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

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

$ svn commit -m "integer.c: ported r344 (spelling fixes) from trunk."
Sending        integer.c
Transmitting file data .
Committed revision 360.

Как вы увидите в последующих разделах, очень важно следовать этой «хорошей практике».

$ svn diff -r 343:344 http://svn.example.com/repos/calc/trunk > patchfile
$ patch -p0  < patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done

Небольшое предупреждение: несмотря на то, что svn diff и svn merge по сути очень похожи, во многих случаях они используют разный синтаксис. Обязательно прочтите об этом в Глава 9, Полное справочное руководство по Subversion, или спросите у svn help. Например, svn merge требует в качестве целевого объекта путь в рабочей копии, то есть место, где ей нужно применить изменения структуры файлов. Если целевой объект не указан, предполагается, что делается попытка выполнить одну из следующих операций:

Если вы объединяете каталог и не указываете целевой путь, svn merge предполагает первый из приведенных выше вариантов и пытается применить изменения к текущему каталогу. Если вы объединяете файл, и при этом файл с таким именем есть в текущем рабочем каталоге, svn merge подразумевает второй случай и пытается применить изменения к локальному файлу с таким же именем.

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

$ svn merge -r 343:344 http://svn.example.com/repos/calc/trunk my-calc-branch
U   my-calc-branch/integer.c

Теперь, после знакомства с примерами использования svn merge, настала пора разобраться в них поглубже. Если вы чувствуете неуверенность в том как, собственно, работает слияние, то вы в этом вы не одиноки. Многие пользователи (особенно те, для которых управление версиями в новинку) поначалу путаются в правильности записи этой команды и в том, как и когда эту функцию следует использовать. Отбросьте страх — на самом деле эта команда намного проще, чем вы думаете! Понять, как именно ведет себя svn merge, очень просто.

В ступор вводит, главным образом, название команды. Термин «слияние» как бы указывает на то, что ветки соединяются вместе, или происходит какое-то волшебное смешивание данных. На самом деле это не так. Пожалуй, этой команде лучше бы подощло название svn diff-and-apply, поскольку это всё, что в результате происходит: сравниваются два файловых дерева хранилища, а различия переносятся в рабочую копию.

Команда принимает три аргумента:

Когда эти три аргумента указаны, производится сравнение двух деревьев, а полученные различия применяются к целевой рабочей копии в виде локальных изменений. После выполнения этой команды результат будет так же, как в случае, если бы вы вручную редактировали файлы или многократно выполняли команды svn add или svn delete. Если результат вас устраивает, его можно зафиксировать. Если результат вас не устраивает, просто отмените (svn revert) все сделанные изменения.

Синтаксис svn merge позволяет указывать эти три аргумента довольно гибко. Вот несколько примеров:

      
$ svn merge http://svn.example.com/repos/branch1@150 \
            http://svn.example.com/repos/branch2@212 \
            my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk

В первом варианте все три аргумента указаны явно — каждое дерево задано в форме URL@REV и указана целевая рабочая копия. Второй вариант может использоваться для краткости записи в ситуациях, когда сравниваются две разных правки по одному и тому же URL. Последний вариант демонстрирует возможность не указывать целевую рабочую копию, при этом по умолчанию используется текущий каталог.

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

Как применить в этом случае svn merge? Помните о том, что эта команда сравнивает два дерева и применяет различия к рабочей копии. Следовательно, для того, чтобы было к чему применять изменения, необходимо иметь рабочую копию главной линии разработки. Будем считать, что такая, полностью обновленная копия у вас либо уже есть, либо вы ее только что создали в каталоге /calc/trunk.

Но какие именно два дерева нужно сравнивать? На первый взгляд ответ очевиден: нужно сравнить последнее дерево главной линии разработки с последним деревом вашей ветки. Однако такое предположение будет ошибочным. Это типичная ошибка большинства новичков! Поскольку svn merge работает так же как и svn diff, сравнение последней версии главной линии разработки и вашей ветки покажет изменения, сделанные не только в вашей ветке. Такое сравнение покажет слишком много изменений. Оно выведет не только то, что добавлялось в вашей ветке, но и то, что удалялось в главной линии разработки и не удалялось в вашей ветке.

Чтобы выделить только те изменения, которые были сделаны в вашей ветке, нужно сравнивать начальное и конечное состояния этой ветки. Посмотрев svn log, можно узнать, что ветка была создана в правке 341. В качестве конечного состояния ветки можно просто использовать правку HEAD. Это значит, что вам нужно сравнить правки 341 и HEAD каталога с веткой и применить различия к рабочей копии главной линии разработки.

Подсказка

Для определения правки, в которой была создана ветка («базовой» правки ветки), удобно использовать параметр --stop-on-copy команды svn log. Обычно эта команда показывает все изменения, сделанные в ветке, включая те, которые были сделаны до создания ветки. Поэтому вы будете видеть и историю главной линии разработки. Параметр --stop-on-copy остановит вывод лог-сообщений, как только svn log обнаружит факт копирования или переименования целевого объекта. $ svn log --verbose --stop-on-copy \ http://svn.example.com/repos/calc/branches/my-calc-branch … ------------------------------------------------------------------------ r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: A /calc/branches/my-calc-branch (from /calc/trunk:340) $ Как и ожидалось, последней строчкой эта команда выведет ту правку, в которой в результате копирования был создан каталог my-calc-branch.

Теперь мы можем завершить объединение веток:

$ cd calc/trunk
$ svn update
At revision 405.

$ svn merge -r 341:405 http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

# ...examine the diffs, compile, test, etc...

$ svn commit -m "Merged my-calc-branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.

Еще раз обратите внимание на то, что в лог-сообщении фиксации очень точно указан диапазон правок, которые были объединены с главной линией разработки. Никогда не забывайте этого делать, потому что это очень важная информация, которая понадобиться вам позже.

Предположим, что на следующей неделе вы решили продолжить работу над своей веткой, чтобы доработать новый функционал или исправить еще несколько ошибок. Теперь правка HEAD хранилища имеет номер 480, и вы готовы еще раз объединить свою личную копию с главной линией разработки. Однако, как уже было сказано в разделе «Как правильнее всего использовать слияние», ранее объединенные изменения не стоит объединять повторно. Объединению подлежат только «новые» изменения, появившиеся с момента последнего объединения. Сложность заключается в том, чтобы выделить эти новые изменения.

Первым шагом будет запуск svn log для главной линии разработки, в результате чего мы узнаем время последнего объединения с веткой:

$ cd calc/trunk
$ svn log
…
------------------------------------------------------------------------
r406 | user | 2004-02-08 11:17:26 -0600 (Sun, 08 Feb 2004) | 1 line

Merged my-calc-branch changes r341:405 into the trunk.
------------------------------------------------------------------------
…

Ага! Все изменения ветки, сделанные между правками 341 и 405, уже были объединены с главной линией разработки в правке 406. Поэтому сейчас нам нужно взять только изменения, выполненные после этого. Для этого мы будем сравнивать правки 406 и HEAD.

$ cd calc/trunk
$ svn update
At revision 480.

# We notice that HEAD is currently 480, so we use it to do the merge:

$ svn merge -r 406:480 http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn commit -m "Merged my-calc-branch changes r406:480 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 481.

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

Еще одной типичной задачей для svn merge является откат ранее сделанных изменений. Предположим, работая в копии /calc/trunk, вы вдруг выясняете, что изменения файла integer.c, сделанные в правке 303, были совершенно ошибочными. Вы можете воспользоваться командой svn merge для «отмены» изменений в своей рабочей копии, после чего зафиксировать локальные изменения в хранилище. Для этого нужно всего лишь указать различия в обратном порядке:

$ svn merge -r 303:302 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

$ svn diff
…
# verify that the change is removed
…

$ svn commit -m "Undoing change committed in r303."
Sending        integer.c
Transmitting file data .
Committed revision 350.

Правку хранилища можно рассматривать как группу изменений (некоторые системы управления версиями называют это набором изменений). Используя параметр -r, можно попросить svn merge применить к рабочей копии набор изменений или целый диапазон наборов изменений. В нашем примере с отменой изменений мы просим svn merge применить к рабочей копии набор изменений #303 в обратном направлении.

Обратите внимание, что подобный откат изменений ничем не отличается от остальных операций, выполняемых с помощью svn merge. Поэтому необходимо с помощью svn status и svn diff убедиться в том, что результат соответствует ожиданиям, а затем, используя svn commit, отправить финальную версию в хранилище. После фиксации этот конкретный набор изменений больше не будет отражен в правке HEAD.

Давайте, однако, подумаем: отменяется ли на самом деле предыдущая фиксация? Изменения продолжают существовать в правке 303. И если кто-то создаст рабочую копию проекта calc между правками 303 и 349, он ведь все равно получит ошибочные изменения?

Безусловно, это так. Говоря об «удалении» изменений, мы имеем в виду их удаление из правки HEAD. Исходные изменения по-прежнему останутся в истории хранилища. Чаще всего это можно рассматривать даже как положительный момент. В любом случае, большинство пользователей интересует только HEAD-правка проекта. Однако, возможны ситуации, когда необходимо полностью удалить последствия фиксации. (Например, если кто-то случайно зафиксировал конфиденциальный документ.) Сделать это будет непросто, так как архитектура Subversion намеренно исключает возможность потери информации. Правки представляют собой не меняющиеся деревья файлов, основанные друг на друге. Удаление правки из хранилища может вызвать эффект домино, потащив за собой все последующие правки и повредив все рабочие копии. ^[26]

Отличным свойством системы управления версиями является то, что информация никогда не теряется. При удалении файла или каталога элемент исключается из правки HEAD, но продолжает существовать в более ранних правках. Новые пользователи очень часто спрашивают: «Как мне вернуть назад свой файл или каталог?»

Для начала было бы неплохо определиться, какой именно элемент мы пытаемся восстановить. Для этого полезно представить все объекты хранилища как точки в двумерной системе координат. Первой координатой будет отдельное дерево правок, в второй — путь в этом дереве. Таким образом, каждая версия файла или каталога может быть задана парой координат.

В отличие от CVS, Subversion не имеет каталога Attic^[27], поэтому для определения искомой пары координат восстанавливаемого объекта нужно вызвать svn log. Лучше всего запустить svn log --verbose в каталоге, который содержал удаленный объект. Параметр --verbose покажет для каждой правки список измененных элементов — в этом случае вам останется только найти ту правку, в которой файл или каталог были удалены. Это можно сделать визуально или обработав вывод команды каким-нибудь инструментом (например, утилитой grep или просто запустив поиск в редакторе).

$ cd parent-dir
$ svn log --verbose
…
------------------------------------------------------------------------
r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines
Changed paths:
   D /calc/trunk/real.c
   M /calc/trunk/integer.c

Added fast fourier transform functions to integer.c.
Removed real.c because code now in double.c.
…

В этом примере предполагается, что вы ищете удаленный файл real.c. Просмотрев логи родительского каталога, вы можете заметить, что этот файл был удален в правке 808. Следовательно, самая последняя версия этого файла была в правке, предшествующей удалению. Вывод: необходимо из правки 807 восстановить путь /calc/trunk/real.c.

Поиск — непростая задача. Теперь, когда нам известно, что именно нужно восстановить, есть две варианта действий.

Во-первых, мы можем посредством svn merge применить правку 808 «в обратном направлении». (Как отменять изменения, мы уже рассматривали, см. «Отмена изменений».) Это приведет к повторному добавлению файла real.c в форме локального изменения. Файл будет запланирован для добавления, и после фиксации будет снова присутствовать в HEAD.

Однако, в данном примере это не самое лучшее решение. Повторное применение правки 808 не только добавит файл real.c. Лог-сообщение показывает, что также будут отменены некоторые изменения в integer.c, что весьма нежелательно. Конечно, можно выполнить обратное слияние с правкой 808, а затем отменить (svn revert) локальные изменения в integer.c, но такой подход плохо масштабируется. Что, если в правке 808 изменилось 90 файлов?

При другом, более аккуратном подходе svn merge вообще не используется, а вместо этого применяется команда svn copy. Просто скопируйте объект, заданный «парой координат» (правка и путь), из хранилища в рабочую копию:

$ svn copy --revision 807 \
           http://svn.example.com/repos/calc/trunk/real.c ./real.c

$ svn status
A  +   real.c

$ svn commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c."
Adding         real.c
Transmitting file data .
Committed revision 1390.

Знак "плюс" в столбце статуса показывает, что элемент не просто запланирован для добавления, а запланирован для добавления «с историей». Subversion запоминает, откуда он был скопирован. В будущем вызов svn log для этого файла будет пересекать точку восстановления файла и прослеживать всю историю, предшествующую правке 807. Другими словами, новый файл real.c на самом деле не является новым; он является прямым потомком исходного файла, который был удален.

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

Управление версиями чаще всего используется при разработке программного обеспечения, поэтому здесь мы вкратце рассмотрим два наиболее часто используемых командами программистов приема ветвления/слияния. Если вы не используете Subversion для разработки программного обеспечения, можете пропустить этот раздел. Если вы — разработчик программного обеспечения, впервые использующий контроль версий, уделите этому разделу пристальное внимание, поскольку опытные разработчики считают использование данных приемов хорошим стилем. Такие приемы не являются специфичными для Subversion; они применимы к любой системе управления версиями. Однако, здесь мы взглянем на них с позиций Subversion.

$ cd trunk-working-copy

$ svn update
At revision 1910.

$ svn merge http://svn.example.com/repos/calc/trunk@1910 \
            http://svn.example.com/repos/calc/branches/mybranch@1910
U  real.c
U  integer.c
A  newdirectory
A  newdirectory/newfile
…

И снова приходит на помощь svn copy. Если вам нужно сделать снимок /calc/trunk в точно таком виде как в правке HEAD, сделайте копию этой директории:

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/tags/release-1.0 \
      -m "Tagging the 1.0 release of the 'calc' project."

Committed revision 351.

В этом примере предполагается, что директория /calc/tags существует. (Если нет, обратитесь к svn mkdir). После того как сделана копия, новая директория release-1.0 навсегда сохранит состояние проекта в таком виде в каком он существовал в правке HEAD на момент создания копии. Конечно, можно более точно указать какую именно правку копировать, возможна ситуация, когда кто-то другой зафиксировал изменения в проекте с которыми вы еще не успели познакомиться. Поэтому, если вы знаете, что правка 350 /calc/trunk это именно тот снимок который вам нужен, можете указать ее передав -r 350 команде svn copy.

Постойте: ведь процедура создания метки такая же как процедура использованная нами при создании ветки? Да, фактически, это так. Subversion не разделяет ветки и метки. И то и другое является обычными директориями, созданными копированием. Как и в случае с ветками, скопированная директория становиться «меткой» только потому, что человек считает ее таковой: если никто не делает фиксаций в эту директорию она будет оставаться снимком. Если в эту директорию начнут делать фиксации она превратится в ветку.

Если вы администрируете хранилище, есть два возможных подхода управления метками. Первый подход «ручной»: в соответствии с правилами проекта решите, где будут находиться метки и убедитесь в том, что все пользователи знают как рассматривать директории скопированные сюда. (То есть убедитесь, что они знают о том что в них нельзя выполнять фиксации.) Второй подход более параноидальный: вы можете воспользоваться одним из скриптов для контроля доступа, поставляемым с Subversion для того, что бы никто ничего другого кроме создания копий в области для создания меток сделать не мог. (См. Глава 6, Настройка сервера.) Однако обычно в параноидальном подходе необходимости нет. Если пользователь непреднамеренно зафиксирует изменения в директорию с меткой, вы можете просто отменить изменения, как это было рассмотрено в предыдущем разделе. Как ни как, это управление версиями.

Иногда вам будет необходим более сложный «снимок», чем одна единственная директория в одной правке.

Например, представим, что ваш проект гораздо больше, чем наш пример calc: допустим он содержит несколько поддиректорий и намного больше файлов. В процессе работы вам может понадобиться создать рабочую копию, содержащую конкретную функциональность и исправленные ошибки. Добиться этого вы можете выборочно возвращая файлы или директории к конкретной правке (используя svn update -r по мере необходимости) или переключая файлы или директории на отдельные ветки (применяя svn switch). По завершении рабочаяя копия будет представлять собой мешанину различных директорий и правок хранилища. После проверки вы поймете, что вам нужна именно такая комбинация.

Время создавать снимок. Копирование одного URL в другой здесь не пройдет. Здесь нужно сделать и сохранить в хранилище снимок именно такой структуры которую имеет рабочая копия. К счастью, svn copy имеет четыре способа использования (о которых вы можете прочитать в Глава 9, Полное справочное руководство по Subversion), включая возможность копировать в хранилище дерево рабочей копии:

$ ls
my-working-copy/

$ svn copy my-working-copy http://svn.example.com/repos/calc/tags/mytag

Committed revision 352.

Теперь в хранилище есть новая директория /calc/tags/mytag которая является полным отражением рабочей копии — смешанные правки, URL, и тому подобное.

Некоторые пользователи находят интересное применение этой возможности. Иногда возникают ситуации, когда в вашей рабочей копии содержится некоторый набор локальных изменений, которые вы хотели бы показать соразработчику. Вместо запуска svn diff и отправки патч-файла (который не сможет отразить изменения в структуре файлов, измененные символьные ссылки или свойства), можно воспользоваться svn copy для «загрузки» рабочей копии в отдельную область хранилища. После чего ваш соразработчик сможет либо воссоздать у себя вашу рабочую копию, либо, воспользовавшись svn merge, получить только внесенные вами изменения.

Существует несколько стандартных, рекомендуемых способов организации хранилища. Как правило, создается директория trunk, в которой находится «главная линия» разработки, директория branches для хранения веток и директория tags для хранения меток. Если хранилище содержит только один проект, обычно создают три директории верхнего уровня:

/trunk
/branches
/tags

Если хранилище содержит несколько проектов, администратор, обычно создает такую структуру для каждого проекта отдельно (за более подробной информацией о «корне проекта» обратитесь в раздел «Choosing a Repository Layout»):

/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags

Конечно, вы можете не использовать такие типовые структуры. Вы можете сделать любую разновидность, которая будет удобна для вас или вашей команды. Помните о том, какой бы вы выбор не сделали, он может быть не окончательным. Хранилище можно реорганизовать в любое время. Учитывая то, что ветки и метки являются обычными директориями, команда svn move может переместить или переименовать их по вашему усмотрению. Переход от одной структуры к другой означает просто несколько последовательных передвижек на сервере; если организация хранилища вам не нравится, просто поменяйте местами директории.

Однако не забывайте о том, что несмотря на легкость перемещения директорий, нужно помнить и о других пользователях. Ваши перестановки могут дезориентировать пользователей с существующими рабочими копиями. Если у пользователя есть рабочая копия отдельной директории хранилища, то ваше использование svn move может удалить этот путь из последней правки. Когда в очередной раз пользователь запустит svn update, он будет проинформирован о том, что его рабочая копия отражает путь, который больше не существует, и пользователь будет вынужден переключиться (svn switch) на новое местоположение.

Еще одним замечательным свойством модели Subversion является то, что ветки и метки могут иметь конечную продолжительность жизни, так же как и все другие версионированные элементы. Например, предположим вы наконец закончили все работы в ваше личной ветке проекта calc. После объединения изменений с /calc/trunk, нет причин продолжать хранить эту ветку:

$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
             -m "Removing obsolete branch of calc project."

Committed revision 375.

Больше вашей ветки не существует. Конечно, на самом деле она не исчезла: просто ее больше нет в правке HEAD, она больше никого не отвлекает. Если воспользоваться командами svn checkout, svn switch или svn list для обращения к ранним правкам, свою старую ветку вы увидите.

Если просмотра удаленной директории не достаточно, вы всегда можете восстановить эту директорию. Восстановление информации в Subversion выполнить очень просто. Если есть директория или файл, который вы хотите вернуть обратно в HEAD, просто воспользуйтесь svn copy -r для того, что бы скопировать его из старой правки:

$ svn copy -r 374 http://svn.example.com/repos/calc/branches/my-calc-branch \
                  http://svn.example.com/repos/calc/branches/my-calc-branch

Committed revision 376.

В нашем примере ваша личная ветка имеет относительно короткую продолжительность жизни: возможно она создавалась для того, что бы исправить ошибку или реализовать новую функцию. После того, как работа завершена, завершена и ветка. При разработке программного обеспечения, тем не менее, часто имеют две «главных» ветки, существующих рядом довольно долгое время. Допустим, пришло время выпустить релиз стабильной версии проекта calc, а вы знаете, что нужна будет пара месяцев для того, что бы вытрясти из программы последние ошибки. Разработчики не должны добавлять в проект новых функции, но при этом и работа не должна останавливаться. В подобной ситуации создается «стабильная» ветка программы, которая существенно изменяться уже не будет:

$ svn copy http://svn.example.com/repos/calc/trunk \
         http://svn.example.com/repos/calc/branches/stable-1.0 \
         -m "Creating stable branch of calc project."

Committed revision 377.

После этого, разработчикам ничего не мешает продолжать добавлять в /calc/trunk новые передовые (или экспериментальные) функции, а в правилах проекта можно указать, что в /calc/branches/stable-1.0 должны фиксироваться только исправления ошибок. По мере того, как будет продвигаться работа над главной линией разработки, исправленные ошибки будут выборочно портироваться в стабильную ветку. Даже после выхода релиза стабильной ветки, она может продолжать поддерживаться долгое время — столько, сколько этот релиз будет продолжать поддерживаться для пользователей.

Managing vendor branches generally works like this. You create a top-level directory (such as /vendor) to hold the vendor branches. Then you import the third party code into a subdirectory of that top-level directory. You then copy that subdirectory into your main development branch (for example, /trunk) at the appropriate location. You always make your local changes in the main development branch. With each new release of the code you are tracking you bring it into the vendor branch and merge the changes into /trunk, resolving whatever conflicts occur between your local changes and the upstream changes.

Perhaps an example will help to clarify this algorithm. We'll use a scenario where your development team is creating a calculator program that links against a third-party complex number arithmetic library, libcomplex. We'll begin with the initial creation of the vendor branch, and the import of the first vendor drop. We'll call our vendor branch directory libcomplex, and our code drops will go into a subdirectory of our vendor branch called current. And since svn import creates all the intermediate parent directories it needs, we can actually accomplish both of these steps with a single command.

$ svn import /path/to/libcomplex-1.0 \
             http://svn.example.com/repos/vendor/libcomplex/current \
             -m 'importing initial 1.0 vendor drop'
…

We now have the current version of the libcomplex source code in /vendor/libcomplex/current. Now, we tag that version (see «Метки») and then copy it into the main development branch. Our copy will create a new directory called libcomplex in our existing calc project directory. It is in this copied version of the vendor data that we will make our customizations.

$ svn copy http://svn.example.com/repos/vendor/libcomplex/current  \
           http://svn.example.com/repos/vendor/libcomplex/1.0      \
           -m 'tagging libcomplex-1.0'
…
$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0  \
           http://svn.example.com/repos/calc/libcomplex        \
           -m 'bringing libcomplex-1.0 into the main branch'
…

We check out our project's main branch—which now includes a copy of the first vendor drop—and we get to work customizing the libcomplex code. Before we know it, our modified version of libcomplex is now completely integrated into our calculator program. ^[29]

A few weeks later, the developers of libcomplex release a new version of their library—version 1.1—which contains some features and functionality that we really want. We'd like to upgrade to this new version, but without losing the customizations we made to the existing version. What we essentially would like to do is to replace our current baseline version of libcomplex 1.0 with a copy of libcomplex 1.1, and then re-apply the custom modifications we previously made to that library to the new version. But we actually approach the problem from the other direction, applying the changes made to libcomplex between versions 1.0 and 1.1 to our modified copy of it.

To perform this upgrade, we checkout a copy of our vendor branch, and replace the code in the current directory with the new libcomplex 1.1 source code. We quite literally copy new files on top of existing files, perhaps exploding the libcomplex 1.1 release tarball atop our existing files and directories. The goal here is to make our current directory contain only the libcomplex 1.1 code, and to ensure that all that code is under version control. Oh, and we want to do this with as little version control history disturbance as possible.

After replacing the 1.0 code with 1.1 code, svn status will show files with local modifications as well as, perhaps, some unversioned or missing files. If we did what we were supposed to do, the unversioned files are only those new files introduced in the 1.1 release of libcomplex—we run svn add on those to get them under version control. The missing files are files that were in 1.0 but not in 1.1, and on those paths we run svn delete. Finally, once our current working copy contains only the libcomplex 1.1 code, we commit the changes we made to get it looking that way.

Our current branch now contains the new vendor drop. We tag the new version (in the same way we previously tagged the version 1.0 vendor drop), and then merge the differences between the tag of the previous version and the new current version into our main development branch.

$ cd working-copies/calc
$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0      \
            http://svn.example.com/repos/vendor/libcomplex/current  \
            libcomplex
… # resolve all the conflicts between their changes and our changes
$ svn commit -m 'merging libcomplex-1.1 into the main branch'
…

In the trivial use case, the new version of our third-party tool would look, from a files-and-directories point of view, just like the previous version. None of the libcomplex source files would have been deleted, renamed or moved to different locations—the new version would contain only textual modifications against the previous one. In a perfect world, our modifications would apply cleanly to the new version of the library, with absolutely no complications or conflicts.

But things aren't always that simple, and in fact it is quite common for source files to get moved around between releases of software. This complicates the process of ensuring that our modifications are still valid for the new version of code, and can quickly degrade into a situation where we have to manually recreate our customizations in the new version. Once Subversion knows about the history of a given source file—including all its previous locations—the process of merging in the new version of the library is pretty simple. But we are responsible for telling Subversion how the source file layout changed from vendor drop to vendor drop.

Vendor drops that contain more than a few deletes, additions and moves complicate the process of upgrading to each successive version of the third-party data. So Subversion supplies the svn_load_dirs.pl script to assist with this process. This script automates the importing steps we mentioned in the general vendor branch management procedure to make sure that mistakes are minimized. You will still be responsible for using the merge commands to merge the new versions of the third-party data into your main development branch, but svn_load_dirs.pl can help you more quickly and easily arrive at that stage.

In short, svn_load_dirs.pl is an enhancement to svn import that has several important characteristics:

svn_load_dirs.pl takes three mandatory arguments. The first argument is the URL to the base Subversion directory to work in. This argument is followed by the URL—relative to the first argument—into which the current vendor drop will be imported. Finally, the third argument is the local directory to import. Using our previous example, a typical run of svn_load_dirs.pl might look like:

$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
…

You can indicate that you'd like svn_load_dirs.pl to tag the new vendor drop by passing the -t command-line option and specifying a tag name. This tag is another URL relative to the first program argument.

$ svn_load_dirs.pl -t libcomplex-1.1                              \
                   http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
…

When you run svn_load_dirs.pl, it examines the contents of your existing «current» vendor drop, and compares them with the proposed new vendor drop. In the trivial case, there will be no files that are in one version and not the other, and the script will perform the new import without incident. If, however, there are discrepancies in the file layouts between versions, svn_load_dirs.pl will prompt you for how you would like to resolve those differences. For example, you will have the opportunity to tell the script that you know that the file math.c in version 1.0 of libcomplex was renamed to arithmetic.c in libcomplex 1.1. Any discrepancies not explained by moves are treated as regular additions and deletions.

The script also accepts a separate configuration file for setting properties on files and directories matching a regular expression that are added to the repository. This configuration file is specified to svn_load_dirs.pl using the -p command-line option. Each line of the configuration file is a whitespace-delimited set of two or four values: a Perl-style regular expression to match the added path against, a control keyword (either break or cont), and then optionally a property name and value.

\.png$              break   svn:mime-type   image/png
\.jpe?g$            break   svn:mime-type   image/jpeg
\.m3u$              cont    svn:mime-type   audio/x-mpegurl
\.m3u$              break   svn:eol-style   LF
.*                  break   svn:eol-style   native

For each added path, the configured property changes whose regular expression matches the path are applied in order, unless the control specification is break (which means that no more property changes should be applied to that path). If the control specification is cont—an abbreviation for continue—then matching will continue with the next line of the configuration file.

Any whitespace in the regular expression, property name, or property value must be surrounded by either single or double quote characters. You can escape quote characters that are not used for wrapping whitespace by preceding them with a backslash (\) character. The backslash escapes only quotes when parsing the configuration file, so do not protect any other characters beyond what is necessary for the regular expression.

Conceptually speaking, a Subversion repository is a sequence of directory trees. Each tree is a snapshot of how the files and directories versioned in your repository looked at some point in time. These snapshots are created as a result of client operations, and are called revisions.

Every revision begins life as a transaction tree. When doing a commit, a client builds a Subversion transaction that mirrors their local changes (plus any additional changes that might have been made to the repository since the beginning of the client's commit process), and then instructs the repository to store that tree as the next snapshot in the sequence. If the commit succeeds, the transaction is effectively promoted into a new revision tree, and is assigned a new revision number. If the commit fails for some reason, the transaction is destroyed and the client is informed of the failure.

Updates work in a similar way. The client builds a temporary transaction tree that mirrors the state of the working copy. The repository then compares that transaction tree with the revision tree at the requested revision (usually the most recent, or «youngest» tree), and sends back information that informs the client about what changes are needed to transform their working copy into a replica of that revision tree. After the update completes, the temporary transaction is deleted.

The use of transaction trees is the only way to make permanent changes to a repository's versioned filesystem. However, it's important to understand that the lifetime of a transaction is completely flexible. In the case of updates, transactions are temporary trees that are immediately destroyed. In the case of commits, transactions are transformed into permanent revisions (or removed if the commit fails). In the case of an error or bug, it's possible that a transaction can be accidentally left lying around in the repository (not really affecting anything, but still taking up space).

In theory, someday whole workflow applications might revolve around more fine-grained control of transaction lifetime. It is feasible to imagine a system whereby each transaction slated to become a revision is left in stasis well after the client finishes describing its changes to repository. This would enable each new commit to be reviewed by someone else, perhaps a manager or engineering QA team, who can choose to promote the transaction into a revision, or abort it.

Transactions and revisions in the Subversion repository can have properties attached to them. These properties are generic key-to-value mappings, and are generally used to store information about the tree to which they are attached. The names and values of these properties are stored in the repository's filesystem, along with the rest of your tree data.

Revision and transaction properties are useful for associating information with a tree that is not strictly related to the files and directories in that tree—the kind of information that isn't managed by client working copies. For example, when a new commit transaction is created in the repository, Subversion adds a property to that transaction named svn:date—a datestamp representing the time that the transaction was created. By the time the commit process is finished, and the transaction is promoted to a permanent revision, the tree has also been given a property to store the username of the revision's author (svn:author) and a property to store the log message attached to that revision (svn:log).

Revision and transaction properties are unversioned properties—as they are modified, their previous values are permanently discarded. Also, while revision trees themselves are immutable, the properties attached to those trees are not. You can add, remove, and modify revision properties at any time in the future. If you commit a new revision and later realize that you had some misinformation or spelling error in your log message, you can simply replace the value of the svn:log property with a new, corrected log message.

As of Subversion 1.1, there are two options for storing data in a Subversion repository. One type of repository stores everything in a Berkeley DB database; the other kind stores data in ordinary flat files, using a custom format. Because Subversion developers often refer to a repository as «the (versioned) filesystem», they have adopted the habit of referring to the latter type of repository as FSFS ^[31] —a versioned filesystem implementation that uses the native OS filesystem to store data.

When a repository is created, an administrator must decide whether it will use Berkeley DB or FSFS. There are advantages and disadvantages to each, which we'll describe in a bit. Neither back-end is more «official» than another, and programs which access the repository are insulated from this implementation detail. Programs have no idea how a repository is storing data; they only see revision and transaction trees through the repository API.

Таблица 5.1, «Repository Data Store Comparison» gives a comparative overview of Berkeley DB and FSFS repositories. The next sections go into detail.

A hook is a program triggered by some repository event, such as the creation of a new revision or the modification of an unversioned property. Each hook is handed enough information to tell what that event is, what target(s) it's operating on, and the username of the person who triggered the event. Depending on the hook's output or return status, the hook program may continue the action, stop it, or suspend it in some way.

The hooks subdirectory is, by default, filled with templates for various repository hooks.

$ ls repos/hooks/
post-commit.tmpl          post-unlock.tmpl          pre-revprop-change.tmpl
post-lock.tmpl            pre-commit.tmpl           pre-unlock.tmpl
post-revprop-change.tmpl  pre-lock.tmpl             start-commit.tmpl

There is one template for each hook that the Subversion repository implements, and by examining the contents of those template scripts, you can see what triggers each such script to run and what data is passed to that script. Also present in many of these templates are examples of how one might use that script, in conjunction with other Subversion-supplied programs, to perform common useful tasks. To actually install a working hook, you need only place some executable program or script into the repos/hooks directory which can be executed as the name (like start-commit or post-commit) of the hook.

On Unix platforms, this means supplying a script or program (which could be a shell script, a Python program, a compiled C binary, or any number of other things) named exactly like the name of the hook. Of course, the template files are present for more than just informational purposes—the easiest way to install a hook on Unix platforms is to simply copy the appropriate template file to a new file that lacks the .tmpl extension, customize the hook's contents, and ensure that the script is executable. Windows, however, uses file extensions to determine whether or not a program is executable, so you would need to supply a program whose basename is the name of the hook, and whose extension is one of the special extensions recognized by Windows for executable programs, such as .exe or .com for programs, and .bat for batch files.

Подсказка

For security reasons, the Subversion repository executes hook scripts with an empty environment—that is, no environment variables are set at all, not even $PATH or %PATH%. Because of this, a lot of administrators are baffled when their hook script runs fine by hand, but doesn't work when run by Subversion. Be sure to explicitly set environment variables in your hook and/or use absolute paths to programs.

There are nine hooks implemented by the Subversion repository:

Внимание

Do not attempt to modify the transaction using hook scripts. A common example of this would be to automatically set properties such as svn:eol-style or svn:mime-type during the commit. While this might seem like a good idea, it causes problems. The main problem is that the client does not know about the change made by the hook script, and there is no way to inform the client that it is out-of-date. This inconsistency can lead to surprising and unexpected behavior. Instead of attempting to modify the transaction, it is much better to check the transaction in the pre-commit hook and reject the commit if it does not meet the desired requirements.

Subversion will attempt to execute hooks as the same user who owns the process which is accessing the Subversion repository. In most cases, the repository is being accessed via Apache HTTP server and mod_dav_svn, so this user is the same user that Apache runs as. The hooks themselves will need to be configured with OS-level permissions that allow that user to execute them. Also, this means that any file or programs (including the Subversion repository itself) accessed directly or indirectly by the hook will be accessed as the same user. In other words, be alert to potential permission-related problems that could prevent the hook from performing the tasks you've written it to perform.

A Berkeley DB environment is an encapsulation of one or more databases, log files, region files and configuration files. The Berkeley DB environment has its own set of default configuration values for things like the number of database locks allowed to be taken out at any given time, or the maximum size of the journaling log files, etc. Subversion's filesystem code additionally chooses default values for some of the Berkeley DB configuration options. However, sometimes your particular repository, with its unique collection of data and access patterns, might require a different set of configuration option values.

The folks at Sleepycat (the producers of Berkeley DB) understand that different databases have different requirements, and so they have provided a mechanism for overriding at runtime many of the configuration values for the Berkeley DB environment. Berkeley checks for the presence of a file named DB_CONFIG in each environment directory, and parses the options found in that file for use with that particular Berkeley environment.

The Berkeley configuration file for your repository is located in the db environment directory, at repos/db/DB_CONFIG. Subversion itself creates this file when it creates the rest of the repository. The file initially contains some default options, as well as pointers to the Berkeley DB online documentation so you can read about what those options do. Of course, you are free to add any of the supported Berkeley DB options to your DB_CONFIG file. Just be aware that while Subversion never attempts to read or interpret the contents of the file, and makes no use of the option settings in it, you'll want to avoid any configuration changes that may cause Berkeley DB to behave in a fashion that is unexpected by the rest of the Subversion code. Also, changes made to DB_CONFIG won't take effect until you recover the database environment (using svnadmin recover).

Subversion provides a handful of utilities useful for creating, inspecting, modifying and repairing your repository. Let's look more closely at each of those tools. Afterward, we'll briefly examine some of the utilities included in the Berkeley DB distribution that provide functionality specific to your repository's database backend not otherwise provided by Subversion's own tools.

$ svnlook help
general usage: svnlook SUBCOMMAND REPOS_PATH [ARGS & OPTIONS ...]
Note: any subcommand which takes the '--revision' and '--transaction'
      options will, if invoked without one of those options, act on
      the repository's youngest revision.
Type "svnlook help <subcommand>" for help on a specific subcommand.
…

$ svnlook info /path/to/repos
$ svnlook info /path/to/repos --revision 19

$ svnlook youngest /path/to/repos
19

$ svnlook info /path/to/repos
sally
2002-11-04 09:29:13 -0600 (Mon, 04 Nov 2002)
27
Added the usual
Greek tree.

$ svnlook tree /path/to/repos --show-ids
/ <0.0.1>
 A/ <2.0.1>
  B/ <4.0.1>
   lambda <5.0.1>
   E/ <6.0.1>
    alpha <7.0.1>
    beta <8.0.1>
   F/ <9.0.1>
  mu <3.0.1>
  C/ <a.0.1>
  D/ <b.0.1>
   gamma <c.0.1>
   G/ <d.0.1>
    pi <e.0.1>
    rho <f.0.1>
    tau <g.0.1>
   H/ <h.0.1>
    chi <i.0.1>
    omega <k.0.1>
    psi <j.0.1>
 iota <1.0.1>

$ svnadmin help
general usage: svnadmin SUBCOMMAND REPOS_PATH  [ARGS & OPTIONS ...]
Type "svnadmin help <subcommand>" for help on a specific subcommand.

Available subcommands:
   create
   deltify
   dump
   help (?, h)
…

svndumpfilter

Since Subversion stores everything in an opaque database system, attempting manual tweaks is unwise, if not quite difficult. And once data has been stored in your repository, Subversion generally doesn't provide an easy way to remove that data. ^[32] But inevitably, there will be times when you would like to manipulate the history of your repository. You might need to strip out all instances of a file that was accidentally added to the repository (and shouldn't be there for whatever reason). Or, perhaps you have multiple projects sharing a single repository, and you decide to split them up into their own repositories. To accomplish tasks like this, administrators need a more manageable and malleable representation of the data in their repositories—the Subversion repository dump format.

The Subversion repository dump format is a human-readable representation of the changes that you've made to your versioned data over time. You use the svnadmin dump command to generate the dump data, and svnadmin load to populate a new repository with it (see «Migrating a Repository»). The great thing about the human-readability aspect of the dump format is that, if you aren't careless about it, you can manually inspect and modify it. Of course, the downside is that if you have two years' worth of repository activity encapsulated in what is likely to be a very large dump file, it could take you a long, long time to manually inspect and modify it.

While it won't be the most commonly used tool at the administrator's disposal, svndumpfilter provides a very particular brand of useful functionality—the ability to quickly and easily modify that dump data by acting as a path-based filter. Simply give it either a list of paths you wish to keep, or a list of paths you wish to not keep, then pipe your repository dump data through this filter. The result will be a modified stream of dump data that contains only the versioned paths you (explicitly or implicitly) requested.

The syntax of svndumpfilter is as follows:

$ svndumpfilter help
general usage: svndumpfilter SUBCOMMAND [ARGS & OPTIONS ...]
Type "svndumpfilter help <subcommand>" for help on a specific subcommand.

Available subcommands:
   exclude
   include
   help (?, h)

There are only two interesting subcommands. They allow you to make the choice between explicit or implicit inclusion of paths in the stream:

exclude

Filter out a set of paths from the dump data stream.

include

Allow only the requested set of paths to pass through the dump data stream.

Let's look a realistic example of how you might use this program. We discuss elsewhere (see «Choosing a Repository Layout») the process of deciding how to choose a layout for the data in your repositories—using one repository per project or combining them, arranging stuff within your repository, and so on. But sometimes after new revisions start flying in, you rethink your layout and would like to make some changes. A common change is the decision to move multiple projects which are sharing a single repository into separate repositories for each project.

Our imaginary repository contains three projects: calc, calendar, and spreadsheet. They have been living side-by-side in a layout like this:

/
   calc/
      trunk/
      branches/
      tags/
   calendar/
      trunk/
      branches/
      tags/
   spreadsheet/
      trunk/
      branches/
      tags/

To get these three projects into their own repositories, we first dump the whole repository:

$ svnadmin dump /path/to/repos > repos-dumpfile
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
* Dumped revision 3.
…
$

Next, run that dump file through the filter, each time including only one of our top-level directories, and resulting in three new dump files:

$ svndumpfilter include calc < repos-dumpfile > calc-dumpfile
…
$ svndumpfilter include calendar < repos-dumpfile > cal-dumpfile
…
$ svndumpfilter include spreadsheet < repos-dumpfile > ss-dumpfile
…
$

At this point, you have to make a decision. Each of your dump files will create a valid repository, but will preserve the paths exactly as they were in the original repository. This means that even though you would have a repository solely for your calc project, that repository would still have a top-level directory named calc. If you want your trunk, tags, and branches directories to live in the root of your repository, you might wish to edit your dump files, tweaking the Node-path and Node-copyfrom-path headers to no longer have that first calc/ path component. Also, you'll want to remove the section of dump data that creates the calc directory. It will look something like:

Node-path: calc
Node-action: add
Node-kind: dir
Content-length: 0

	Внимание
	If you do plan on manually editing the dump file to remove a top-level directory, make sure that your editor is not set to automatically convert end-lines to the native format (e.g. \r\n to \n) as the content will then not agree with the metadata and this will render the dump file useless.

All that remains now is to create your three new repositories, and load each dump file into the right repository:

$ svnadmin create calc; svnadmin load calc < calc-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : button.c ... done.
…
$ svnadmin create calendar; svnadmin load calendar < cal-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : cal.c ... done.
…
$ svnadmin create spreadsheet; svnadmin load spreadsheet < ss-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : ss.c ... done.
…
$

Both of svndumpfilter's subcommands accept options for deciding how to deal with «empty» revisions. If a given revision contained only changes to paths that were filtered out, that now-empty revision could be considered uninteresting or even unwanted. So to give the user control over what to do with those revisions, svndumpfilter provides the following command-line options:

--drop-empty-revs

Do not generate empty revisions at all—just omit them.

--renumber-revs

If empty revisions are dropped (using the --drop-empty-revs option), change the revision numbers of the remaining revisions so that there are no gaps in the numeric sequence.

--preserve-revprops

If empty revisions are not dropped, preserve the revision properties (log message, author, date, custom properties, etc.) for those empty revisions. Otherwise, empty revisions will only contain the original datestamp, and a generated log message that indicates that this revision was emptied by svndumpfilter.

While svndumpfilter can be very useful, and a huge timesaver, there are unfortunately a couple of gotchas. First, this utility is overly sensitive to path semantics. Pay attention to whether paths in your dump file are specified with or without leading slashes. You'll want to look at the Node-path and Node-copyfrom-path headers.

…
Node-path: spreadsheet/Makefile
…

If the paths have leading slashes, you should include leading slashes in the paths you pass to svndumpfilter include and svndumpfilter exclude (and if they don't, you shouldn't). Further, if your dump file has an inconsistent usage of leading slashes for some reason, ^[33] you should probably normalize those paths so they all have, or lack, leading slashes.

Also, copied paths can give you some trouble. Subversion supports copy operations in the repository, where a new path is created by copying some already existing path. It is possible that at some point in the lifetime of your repository, you might have copied a file or directory from some location that svndumpfilter is excluding, to a location that it is including. In order to make the dump data self-sufficient, svndumpfilter needs to still show the addition of the new path—including the contents of any files created by the copy—and not represent that addition as a copy from a source that won't exist in your filtered dump data stream. But because the Subversion repository dump format only shows what was changed in each revision, the contents of the copy source might not be readily available. If you suspect that you have any copies of this sort in your repository, you might want to rethink your set of included/excluded paths.

Your Subversion repository will generally require very little attention once it is configured to your liking. However, there are times when some manual assistance from an administrator might be in order. The svnadmin utility provides some helpful functionality to assist you in performing such tasks as:

Perhaps the most commonly used of svnadmin's subcommands is setlog. When a transaction is committed to the repository and promoted to a revision, the descriptive log message associated with that new revision (and provided by the user) is stored as an unversioned property attached to the revision itself. In other words, the repository remembers only the latest value of the property, and discards previous ones.

Sometimes a user will have an error in her log message (a misspelling or some misinformation, perhaps). If the repository is configured (using the pre-revprop-change and post-revprop-change hooks; see «Hook Scripts») to accept changes to this log message after the commit is finished, then the user can «fix» her log message remotely using the svn program's propset command (see Глава 9, Полное справочное руководство по Subversion). However, because of the potential to lose information forever, Subversion repositories are not, by default, configured to allow changes to unversioned properties—except by an administrator.

If a log message needs to be changed by an administrator, this can be done using svnadmin setlog. This command changes the log message (the svn:log property) on a given revision of a repository, reading the new value from a provided file.

$ echo "Here is the new, correct log message" > newlog.txt
$ svnadmin setlog myrepos newlog.txt -r 388

The svnadmin setlog command alone is still bound by the same protections against modifying unversioned properties as a remote client is—the pre- and post-revprop-change hooks are still triggered, and therefore must be setup to accept changes of this nature. But an administrator can get around these protections by passing the --bypass-hooks option to the svnadmin setlog command.

	Внимание
	Remember, though, that by bypassing the hooks, you are likely avoiding such things as email notifications of property changes, backup systems which track unversioned property changes, and so on. In other words, be very careful about what you are changing, and how you change it.

Another common use of svnadmin is to query the repository for outstanding—possibly dead—Subversion transactions. In the event that a commit should fail, the transaction is usually cleaned up. That is, the transaction itself is removed from the repository, and any data associated with (and only with) that transaction is removed as well. Occasionally, though, a failure occurs in such a way that the cleanup of the transaction never happens. This could happen for several reasons: perhaps the client operation was inelegantly terminated by the user, or a network failure might have occurred in the middle of an operation, etc. Regardless of the reason, dead transactions can happen. They don't do any real harm, other than consuming a small bit of disk space. A fastidious administrator may nonetheless want to remove them.

You can use svnadmin's lstxns command to list the names of the currently outstanding transactions.

$ svnadmin lstxns myrepos
19
3a1
a45
$

Each item in the resultant output can then be used with svnlook (and its --transaction option) to determine who created the transaction, when it was created, what types of changes were made in the transaction—in other words, whether or not the transaction is a safe candidate for removal! If so, the transaction's name can be passed to svnadmin rmtxns, which will perform the cleanup of the transaction. In fact, the rmtxns subcommand can take its input directly from the output of lstxns!

$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos`
$

If you use these two subcommands like this, you should consider making your repository temporarily inaccessible to clients. That way, no one can begin a legitimate transaction before you start your cleanup. The following is a little bit of shell-scripting that can quickly generate information about each outstanding transaction in your repository:

#!/bin/sh

### Generate informational output for all outstanding transactions in
### a Subversion repository.

REPOS="${1}"
if [ "x$REPOS" = x ] ; then
  echo "usage: $0 REPOS_PATH"
  exit
fi

for TXN in `svnadmin lstxns ${REPOS}`; do
  echo "---[ Transaction ${TXN} ]-------------------------------------------"
  svnlook info "${REPOS}" --transaction "${TXN}"
done

You can run the previous script using /path/to/txn-info.sh /path/to/repos. The output is basically a concatenation of several chunks of svnlook info output (see «svnlook»), and will look something like:

$ txn-info.sh myrepos
---[ Transaction 19 ]-------------------------------------------
sally
2001-09-04 11:57:19 -0500 (Tue, 04 Sep 2001)
0
---[ Transaction 3a1 ]-------------------------------------------
harry
2001-09-10 16:50:30 -0500 (Mon, 10 Sep 2001)
39
Trying to commit over a faulty network.
---[ Transaction a45 ]-------------------------------------------
sally
2001-09-12 11:09:28 -0500 (Wed, 12 Sep 2001)
0
$

A long-abandoned transaction usually represents some sort of failed or interrupted commit. A transaction's datestamp can provide interesting information—for example, how likely is it that an operation begun nine months ago is still active?

In short, transaction cleanup decisions need not be made unwisely. Various sources of information—including Apache's error and access logs, the logs of successful Subversion commits, and so on—can be employed in the decision-making process. Finally, an administrator can often simply communicate with a seemingly dead transaction's owner (via email, for example) to verify that the transaction is, in fact, in a zombie state.

While the cost of storage has dropped incredibly in the past few years, disk usage is still a valid concern for administrators seeking to version large amounts of data. Every additional byte consumed by the live repository is a byte that needs to be backed up offsite, perhaps multiple times as part of rotating backup schedules. If using a Berkeley DB repository, the primary storage mechanism is a complex database system, it is useful to know what pieces of data need to remain on the live site, which need to be backed up, and which can be safely removed. This section is specific to Berkeley DB; FSFS repositories have no extra data to be cleaned up or reclaimed.

Until recently, the largest offender of disk space usage with respect to Subversion repositories was the log files to which Berkeley DB performs its pre-writes before modifying the actual database files. These files capture all the actions taken along the route of changing the database from one state to another—while the database files reflect at any given time some state, the log files contain all the many changes along the way between states. As such, they can start to accumulate quite rapidly.

Fortunately, beginning with the 4.2 release of Berkeley DB, the database environment has the ability to remove its own unused log files without any external procedures. Any repositories created using an svnadmin which is compiled against Berkeley DB version 4.2 or greater will be configured for this automatic log file removal. If you don't want this feature enabled, simply pass the --bdb-log-keep option to the svnadmin create command. If you forget to do this, or change your mind at a later time, simple edit the DB_CONFIG file found in your repository's db directory, comment out the line which contains the set_flags DB_LOG_AUTOREMOVE directive, and then run svnadmin recover on your repository to force the configuration changes to take effect. See «Berkeley DB Configuration» for more information about database configuration.

Without some sort of automatic log file removal in place, log files will accumulate as you use your repository. This is actually somewhat of a feature of the database system—you should be able to recreate your entire database using nothing but the log files, so these files can be useful for catastrophic database recovery. But typically, you'll want to archive the log files that are no longer in use by Berkeley DB, and then remove them from disk to conserve space. Use the svnadmin list-unused-dblogs command to list the unused log files:

$ svnadmin list-unused-dblogs /path/to/repos
/path/to/repos/log.0000000031
/path/to/repos/log.0000000032
/path/to/repos/log.0000000033

$ svnadmin list-unused-dblogs /path/to/repos | xargs rm
## disk space reclaimed!

To keep the size of the repository as small as possible, Subversion uses deltification (or, «deltified storage») within the repository itself. Deltification involves encoding the representation of a chunk of data as a collection of differences against some other chunk of data. If the two pieces of data are very similar, this deltification results in storage savings for the deltified chunk—rather than taking up space equal to the size of the original data, it only takes up enough space to say, «I look just like this other piece of data over here, except for the following couple of changes». Specifically, each time a new version of a file is committed to the repository, Subversion encodes the previous version (actually, several previous versions) as a delta against the new version. The result is that most of the repository data that tends to be sizable—namely, the contents of versioned files—is stored at a much smaller size than the original «fulltext» representation of that data.

Замечание

Because all of the Subversion repository data that is subject to deltification is stored in a single Berkeley DB database file, reducing the size of the stored values will not necessarily reduce the size of the database file itself. Berkeley DB will, however, keep internal records of unused areas of the database file, and use those areas first before growing the size of the database file. So while deltification doesn't produce immediate space savings, it can drastically slow future growth of the database.

As mentioned in «Berkeley DB», a Berkeley DB repository can sometimes be left in frozen state if not closed properly. When this happens, an administrator needs to rewind the database back into a consistent state.

In order to protect the data in your repository, Berkeley DB uses a locking mechanism. This mechanism ensures that portions of the database are not simultaneously modified by multiple database accessors, and that each process sees the data in the correct state when that data is being read from the database. When a process needs to change something in the database, it first checks for the existence of a lock on the target data. If the data is not locked, the process locks the data, makes the change it wants to make, and then unlocks the data. Other processes are forced to wait until that lock is removed before they are permitted to continue accessing that section of the database. (This has nothing to do with the locks that you, as a user, can apply to versioned files within the repository; see Three meanings of «lock» for more information.)

In the course of using your Subversion repository, fatal errors (such as running out of disk space or available memory) or interruptions can prevent a process from having the chance to remove the locks it has placed in the database. The result is that the back-end database system gets «wedged». When this happens, any attempts to access the repository hang indefinitely (since each new accessor is waiting for a lock to go away—which isn't going to happen).

First, if this happens to your repository, don't panic. The Berkeley DB filesystem takes advantage of database transactions and checkpoints and pre-write journaling to ensure that only the most catastrophic of events ^[34] can permanently destroy a database environment. A sufficiently paranoid repository administrator will be making off-site backups of the repository data in some fashion, but don't call your system administrator to restore a backup tape just yet.

Secondly, use the following recipe to attempt to «unwedge» your repository:

This procedure fixes almost every case of repository lock-up. Make sure that you run this command as the user that owns and manages the database, not just as root. Part of the recovery process might involve recreating from scratch various database files (shared memory regions, for example). Recovering as root will create those files such that they are owned by root, which means that even after you restore connectivity to your repository, regular users will be unable to access it.

If the previous procedure, for some reason, does not successfully unwedge your repository, you should do two things. First, move your broken repository out of the way and restore your latest backup of it. Then, send an email to the Subversion user list (at <users@subversion.tigris.org>) describing your problem in detail. Data integrity is an extremely high priority to the Subversion developers.

A Subversion filesystem has its data spread throughout various database tables in a fashion generally understood by (and of interest to) only the Subversion developers themselves. However, circumstances may arise that call for all, or some subset, of that data to be collected into a single, portable, flat file format. Subversion provides such a mechanism, implemented in a pair of svnadmin subcommands: dump and load.

The most common reason to dump and load a Subversion repository is due to changes in Subversion itself. As Subversion matures, there are times when certain changes made to the back-end database schema cause Subversion to be incompatible with previous versions of the repository. Other reasons for dumping and loading might be to migrate a Berkeley DB repository to a new OS or CPU architecture, or to switch between Berkeley DB and FSFS back-ends. The recommended course of action is relatively simple:

svnadmin dump will output a range of repository revisions that are formatted using Subversion's custom filesystem dump format. The dump format is printed to the standard output stream, while informative messages are printed to the standard error stream. This allows you to redirect the output stream to a file while watching the status output in your terminal window. For example:

$ svnlook youngest myrepos
26
$ svnadmin dump myrepos > dumpfile
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
…
* Dumped revision 25.
* Dumped revision 26.

At the end of the process, you will have a single file (dumpfile in the previous example) that contains all the data stored in your repository in the requested range of revisions. Note that svnadmin dump is reading revision trees from the repository just like any other «reader» process would (svn checkout, for example). So it's safe to run this command at any time.

The other subcommand in the pair, svnadmin load, parses the standard input stream as a Subversion repository dump file, and effectively replays those dumped revisions into the target repository for that operation. It also gives informative feedback, this time using the standard output stream:

$ svnadmin load newrepos < dumpfile
<<< Started new txn, based on original revision 1
     * adding path : A ... done.
     * adding path : A/B ... done.
     …
------- Committed new rev 1 (loaded from original rev 1) >>>

<<< Started new txn, based on original revision 2
     * editing path : A/mu ... done.
     * editing path : A/D/G/rho ... done.

------- Committed new rev 2 (loaded from original rev 2) >>>

…

<<< Started new txn, based on original revision 25
     * editing path : A/D/gamma ... done.

------- Committed new rev 25 (loaded from original rev 25) >>>

<<< Started new txn, based on original revision 26
     * adding path : A/Z/zeta ... done.
     * editing path : A/mu ... done.

------- Committed new rev 26 (loaded from original rev 26) >>>

The result of a load is new revisions added to a repository—the same thing you get by making commits against that repository from a regular Subversion client. And just as in a commit, you can use hook scripts to perform actions before and after each of the commits made during a load process. By passing the --use-pre-commit-hook and --use-post-commit-hook options to svnadmin load, you can instruct Subversion to execute the pre-commit and post-commit hook scripts, respectively, for each loaded revision. You might use these, for example, to ensure that loaded revisions pass through the same validation steps that regular commits pass through. Of course, you should use these options with care—if your post-commit hook sends emails to a mailing list for each new commit, you might not want to spew hundreds or thousands of commit emails in rapid succession at that list for each of the loaded revisions! You can read more about the use of hook scripts in «Hook Scripts».

Note that because svnadmin uses standard input and output streams for the repository dump and load process, people who are feeling especially saucy can try things like this (perhaps even using different versions of svnadmin on each side of the pipe):

$ svnadmin create newrepos
$ svnadmin dump myrepos | svnadmin load newrepos

By default, the dump file will be quite large—much larger than the repository itself. That's because every version of every file is expressed as a full text in the dump file. This is the fastest and simplest behavior, and nice if you're piping the dump data directly into some other process (such as a compression program, filtering program, or into a loading process). But if you're creating a dump file for longer-term storage, you'll likely want to save disk space by using the --deltas switch. With this option, successive revisions of files will be output as compressed, binary differences—just as file revisions are stored in a repository. This option is slower, but results in a dump file much closer in size to the original repository.

We mentioned previously that svnadmin dump outputs a range of revisions. Use the --revision option to specify a single revision to dump, or a range of revisions. If you omit this option, all the existing repository revisions will be dumped.

$ svnadmin dump myrepos --revision 23 > rev-23.dumpfile
$ svnadmin dump myrepos --revision 100:200 > revs-100-200.dumpfile

As Subversion dumps each new revision, it outputs only enough information to allow a future loader to re-create that revision based on the previous one. In other words, for any given revision in the dump file, only the items that were changed in that revision will appear in the dump. The only exception to this rule is the first revision that is dumped with the current svnadmin dump command.

By default, Subversion will not express the first dumped revision as merely differences to be applied to the previous revision. For one thing, there is no previous revision in the dump file! And secondly, Subversion cannot know the state of the repository into which the dump data will be loaded (if it ever, in fact, occurs). To ensure that the output of each execution of svnadmin dump is self-sufficient, the first dumped revision is by default a full representation of every directory, file, and property in that revision of the repository.

However, you can change this default behavior. If you add the --incremental option when you dump your repository, svnadmin will compare the first dumped revision against the previous revision in the repository, the same way it treats every other revision that gets dumped. It will then output the first revision exactly as it does the rest of the revisions in the dump range—mentioning only the changes that occurred in that revision. The benefit of this is that you can create several small dump files that can be loaded in succession, instead of one large one, like so:

$ svnadmin dump myrepos --revision 0:1000 > dumpfile1
$ svnadmin dump myrepos --revision 1001:2000 --incremental > dumpfile2
$ svnadmin dump myrepos --revision 2001:3000 --incremental > dumpfile3

These dump files could be loaded into a new repository with the following command sequence:

$ svnadmin load newrepos < dumpfile1
$ svnadmin load newrepos < dumpfile2
$ svnadmin load newrepos < dumpfile3

Another neat trick you can perform with this --incremental option involves appending to an existing dump file a new range of dumped revisions. For example, you might have a post-commit hook that simply appends the repository dump of the single revision that triggered the hook. Or you might have a script that runs nightly to append dump file data for all the revisions that were added to the repository since the last time the script ran. Used like this, svnadmin's dump and load commands can be a valuable means by which to backup changes to your repository over time in case of a system crash or some other catastrophic event.

The dump format can also be used to merge the contents of several different repositories into a single repository. By using the --parent-dir option of svnadmin load, you can specify a new virtual root directory for the load process. That means if you have dump files for three repositories, say calc-dumpfile, cal-dumpfile, and ss-dumpfile, you can first create a new repository to hold them all:

$ svnadmin create /path/to/projects
$

Then, make new directories in the repository which will encapsulate the contents of each of the three previous repositories:

$ svn mkdir -m "Initial project roots" \
      file:///path/to/projects/calc \
      file:///path/to/projects/calendar \
      file:///path/to/projects/spreadsheet
Committed revision 1.
$

Lastly, load the individual dump files into their respective locations in the new repository:

$ svnadmin load /path/to/projects --parent-dir calc < calc-dumpfile
…
$ svnadmin load /path/to/projects --parent-dir calendar < cal-dumpfile
…
$ svnadmin load /path/to/projects --parent-dir spreadsheet < ss-dumpfile
…
$

We'll mention one final way to use the Subversion repository dump format—conversion from a different storage mechanism or version control system altogether. Because the dump file format is, for the most part, human-readable, ^[35] it should be relatively easy to describe generic sets of changes—each of which should be treated as a new revision—using this file format. In fact, the cvs2svn utility (see «Converting a Repository from CVS to Subversion») uses the dump format to represent the contents of a CVS repository so that those contents can be copied into a Subversion repository.

Despite numerous advances in technology since the birth of the modern computer, one thing unfortunately rings true with crystalline clarity—sometimes, things go very, very awry. Power outages, network connectivity dropouts, corrupt RAM and crashed hard drives are but a taste of the evil that Fate is poised to unleash on even the most conscientious administrator. And so we arrive at a very important topic—how to make backup copies of your repository data.

There are generally two types of backup methods available for Subversion repository administrators—incremental and full. We discussed in an earlier section of this chapter how to use svnadmin dump --incremental to perform an incremental backup (see «Migrating a Repository»). Essentially, the idea is to only backup at a given time the changes to the repository since the last time you made a backup.

A full backup of the repository is quite literally a duplication of the entire repository directory (which includes either Berkeley database or FSFS environment). Now, unless you temporarily disable all other access to your repository, simply doing a recursive directory copy runs the risk of generating a faulty backup, since someone might be currently writing to the database.

In the case of Berkeley DB, Sleepycat documents describe a certain order in which database files can be copied that will guarantee a valid backup copy. And a similar ordering exists for FSFS data. Better still, you don't have to implement these algorithms yourself, because the Subversion development team has already done so. The hot-backup.py script is found in the tools/backup/ directory of the Subversion source distribution. Given a repository path and a backup location, hot-backup.py—which is really just a more intelligent wrapper around the svnadmin hotcopy command—will perform the necessary steps for backing up your live repository—without requiring that you bar public repository access at all—and then will clean out the dead Berkeley log files from your live repository.

Even if you also have an incremental backup, you might want to run this program on a regular basis. For example, you might consider adding hot-backup.py to a program scheduler (such as cron on Unix systems). Or, if you prefer fine-grained backup solutions, you could have your post-commit hook script call hot-backup.py (see «Hook Scripts»), which will then cause a new backup of your repository to occur with every new revision created. Simply add the following to the hooks/post-commit script in your live repository directory:

(cd /path/to/hook/scripts; ./hot-backup.py ${REPOS} /path/to/backups &)

The resulting backup is a fully functional Subversion repository, able to be dropped in as a replacement for your live repository should something go horribly wrong.

There are benefits to both types of backup methods. The easiest is by far the full backup, which will always result in a perfect working replica of your repository. This again means that should something bad happen to your live repository, you can restore from the backup with a simple recursive directory copy. Unfortunately, if you are maintaining multiple backups of your repository, these full copies will each eat up just as much disk space as your live repository.

Incremental backups using the repository dump format are excellent to have on hand if the database schema changes between successive versions of Subversion itself. Since a complete repository dump and load are generally required to upgrade your repository to the new schema, it's very convenient to already have half of that process (the dump part) finished. Unfortunately, the creation of—and restoration from—incremental backups takes longer, as each commit is effectively replayed into either the dump file or the repository.

In either backup scenario, repository administrators need to be aware of how modifications to unversioned revision properties affect their backups. Since these changes do not themselves generate new revisions, they will not trigger post-commit hooks, and may not even trigger the pre-revprop-change and post-revprop-change hooks. ^[36] And since you can change revision properties without respect to chronological order—you can change any revision's properties at any time—an incremental backup of the latest few revisions might not catch a property modification to a revision that was included as part of a previous backup.

Generally speaking, only the truly paranoid would need to backup their entire repository, say, every time a commit occurred. However, assuming that a given repository has some other redundancy mechanism in place with relatively fine granularity (like per-commit emails), a hot backup of the database might be something that a repository administrator would want to include as part of a system-wide nightly backup. For most repositories, archived commit emails alone provide sufficient redundancy as restoration sources, at least for the most recent few commits. But it's your data—protect it as much as you'd like.

Often, the best approach to repository backups is a diversified one. You can leverage combinations of full and incremental backups, plus archives of commit emails. The Subversion developers, for example, back up the Subversion source code repository after every new revision is created, and keep an archive of all the commit and property change notification emails. Your solution might be similar, but should be catered to your needs and that delicate balance of convenience with paranoia. And while all of this might not save your hardware from the iron fist of Fate, ^[37] it should certainly help you recover from those trying times.

While Subversion allows you to move around versioned files and directories without any loss of information, doing so can still disrupt the workflow of those who access the repository often and come to expect things to be at certain locations. Try to peer into the future a bit; plan ahead before placing your data under version control. By «laying out» the contents of your repositories in an effective manner the first time, you can prevent a load of future headaches.

There are a few things to consider when setting up Subversion repositories. Let's assume that as repository administrator, you will be responsible for supporting the version control system for several projects. The first decision is whether to use a single repository for multiple projects, or to give each project its own repository, or some compromise of these two.

There are benefits to using a single repository for multiple projects, most obviously the lack of duplicated maintenance. A single repository means that there is one set of hook scripts, one thing to routinely backup, one thing to dump and load if Subversion releases an incompatible new version, and so on. Also, you can move data between projects easily, and without losing any historical versioning information.

The downside of using a single repository is that different projects may have different commit mailing lists or different authentication and authorization requirements. Also, remember that Subversion uses repository-global revision numbers. Some folks don't like the fact that even though no changes have been made to their project lately, the youngest revision number for the repository keeps climbing because other projects are actively adding new revisions.

A middle-ground approach can be taken, too. For example, projects can be grouped by how well they relate to each other. You might have a few repositories with a handful of projects in each repository. That way, projects that are likely to want to share data can do so easily, and as new revisions are added to the repository, at least the developers know that those new revisions are at least remotely related to everyone who uses that repository.

After deciding how to organize your projects with respect to repositories, you'll probably want to think about directory hierarchies in the repositories themselves. Because Subversion uses regular directory copies for branching and tagging (see Глава 4, Ветвление и слияние), the Subversion community recommends that you choose a repository location for each project root—the «top-most» directory which contains data related to that project—and then create three subdirectories beneath that root: trunk, meaning the directory under which the main project development occurs; branches, which is a directory in which to create various named branches of the main development line; tags, which is a directory of branches that are created, and perhaps destroyed, but never changed. ^[38]

For example, your repository might look like:

/
   calc/
      trunk/
      tags/
      branches/
   calendar/
      trunk/
      tags/
      branches/
   spreadsheet/
      trunk/
      tags/
      branches/
   …

Note that it doesn't matter where in your repository each project root is. If you have only one project per repository, the logical place to put each project root is at the root of that project's respective repository. If you have multiple projects, you might want to arrange them in groups inside the repository, perhaps putting projects with similar goals or shared code in the same subdirectory, or maybe just grouping them alphabetically. Such an arrangement might look like:

/
   utils/
      calc/
         trunk/
         tags/
         branches/
      calendar/
         trunk/
         tags/
         branches/
      …
   office/
      spreadsheet/
         trunk/
         tags/
         branches/
      …

Lay out your repository in whatever way you see fit. Subversion does not expect or enforce a layout schema—in its eyes, a directory is a directory is a directory. Ultimately, you should choose the repository arrangement that meets the needs of the people who work on the projects that live there.

After deciding how to arrange the projects in your repository, you'll probably want to actually populate the repository with that layout and with initial project data. There are a couple of ways to do this in Subversion. You could use the svn mkdir command (see Глава 9, Полное справочное руководство по Subversion) to create each directory in your skeletal repository layout, one-by-one. A quicker way to accomplish the same task is to use the svn import command (see «svn import»). By first creating the layout in a temporary location on your drive, you can import the whole layout tree into the repository in a single commit:

$ mkdir tmpdir
$ cd tmpdir
$ mkdir projectA
$ mkdir projectA/trunk
$ mkdir projectA/branches
$ mkdir projectA/tags
$ mkdir projectB
$ mkdir projectB/trunk
$ mkdir projectB/branches
$ mkdir projectB/tags
…
$ svn import . file:///path/to/repos --message "Initial repository layout"
Adding         projectA
Adding         projectA/trunk
Adding         projectA/branches
Adding         projectA/tags
Adding         projectB
Adding         projectB/trunk
Adding         projectB/branches
Adding         projectB/tags
…
Committed revision 1.
$ cd ..
$ rm -rf tmpdir
$

You can verify the results of the import by running the svn list command:

$ svn list --verbose file:///path/to/repos
      1 harry               May 08 21:48 projectA/
      1 harry               May 08 21:48 projectB/
…
$

Once you have your skeletal layout in place, you can begin importing actual project data into your repository, if any such data exists yet. Once again, there are several ways to do this. You could use the svn import command. You could checkout a working copy from your new repository, move and arrange project data inside the working copy, and use the svn add and svn commit commands. But once we start talking about such things, we're no longer discussing repository administration. If you aren't already familiar with the svn client program, see Глава 2, Экскурсия по Subversion.