Управление версиями в Subversion Для Subversion 3 (в редакции 2345) Бен Коллинз-Сассман

Свойства

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

Подобные приведенным выше, свойства используются и Subversion. Так же как и произвольные имена свойств и соответствующие им значения, имеются у файлов и директорий, каждая правка может иметь произвольные свойства, присоединенные к ней. С теми же исключениями — читаемое, текстовое имя и любое бинарное значение — исключая версионирование свойств правок. Подробнее о таких неверсионированных свойствах см. «Unversioned Properties».

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

Зачем нужны свойства?

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

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

Как (и для чего) использовать Subversion-свойства вы решаете самостоятельно. Как уже говорилось, Subversion имеет свои применения свойств, которые мы рассмотрим в этой главе немного позже. А с начала давйте поговорим как работать со свойствами используя программу svn.

Использование свойств

$ svn propset copyright '(c) 2003 Red-Bean Software' calc/button.c

property 'copyright' set on 'calc/button.c'

$

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

property 'license' set on 'calc/button.c'

$

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

$ svn propedit copyright calc/button.c ### exit the editor without changes

No changes to property 'copyright' on 'calc/button.c'

$

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

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, запросить его значение. Эта команда выведет на стандартный поток ввода-вывода значение свойства для элемента по указанному пути (или путями) и с указанным именем.

Properties on 'calc/button.c':

copyright

license

(c) 2003 Red-Bean Software

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

$ svn proplist --verbose calc/button.c

Properties on 'calc/button.c':

copyright : (c) 2003 Red-Bean Software

license : ================================================================

Copyright (c) 2003 Red-Bean Software. All rights reserved.

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, нельзя. Например, такая команда не даст желаемого эффекта:

property 'license' set on 'calc/button.c'

$ svn proplist --verbose calc/button.c

Properties on 'calc/button.c':

copyright : (c) 2003 Red-Bean Software

license :

$

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

property 'license' deleted from ''.

$ svn proplist --verbose calc/button.c

Properties on 'calc/button.c':

copyright : (c) 2003 Red-Bean Software

$

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

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

$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop

property 'svn:log' set on repository revision '11'

$

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

$ svn status calc/button.c

M calc/button.c

$ svn diff calc/button.c

Property changes on: calc/button.c

___________________________________________________________________

Name: copyright

+ (c) 2003 Red-Bean Software

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

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

% svn update calc

M calc/Makefile.in

C calc/button.c

Updated to revision 143.

$

В директории с конфликтующим элементом Subversion создает файл с расширением .prej, с подробностями о конфликте. Для разрешения конфликта необходимо познакомиться с содержимым этого файла. Пока не будет решен конфликт, во второй колонке вывода команды svn status будет присутствовать буква C, а попытки фиксации локальных изменений будут отклоняться.

C calc/button.c

? calc/button.c.prej

$ cat calc/button.c.prej

prop 'linecount': user set to '1256', but update set to '1301'.

$

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

Как видите, наличие измененных свойств никак не отражается на привычном рабочем цикле. Операции обновления рабочей копии, проверки статуса файлов и директорий, вывод сообщений о сделанных изменениях и фиксация этих измениий в хранилище никак не зависят от наличия или отсутствия свойств. У svn просто имеется несколько дополнительных подкоманд для внесения изменений в свойства однако это просто достойное внимания отличие.

Специальные свойства

svn:executable

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

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

svn:mime-type

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

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

svn:ignore

The rationale behind the svn:ignore property is easily explained. Subversion does not assume that every file or subdirectory in a working copy directory is intended for version control. Resources must be explicitly placed under Subversion's management using the svn add or svn import commands. As a result, there are often many resources in a working copy that are not versioned.

Now, the svn status command displays as part of its output every unversioned file or subdirectory in a working copy that is not already filtered out by the global-ignores option (or its built-in default value). This is done so that users can see if perhaps they've forgotten to add a resource to version control.

But Subversion cannot possibly guess the names of every resource that should be ignored. Also, quite often there are things that should be ignored in every working copy of a particular repository. To force every user of that repository to add patterns for those resources to their run-time configuration areas would be not just a burden, but has the potential to clash with the configuration needs of other working copies that the user has checked out.

The solution is to store ignore patterns that are unique to the resources likely to appear in a given directory with the directory itself. Common examples of unversioned resources that are basically unique to a directory, yet likely to appear there, include output from program compilations. Or—to use an example more appropriate to this book—the HTML, PDF, or PostScript files generated as the result of a conversion of some source DocBook XML files to a more legible output format.

Ignore Patterns for CVS Users

The Subversion svn:ignore property is very similar in syntax and function to the CVS .cvsignore file. In fact, if you are migrating a CVS working copy to Subversion, you can directly migrate the ignore patterns by using the .cvsignore file as input file to the svn propset command:

$ svn propset svn:ignore -F .cvsignore .

property 'svn:ignore' set on '.'

$

There are, however, some differences in the ways that CVS and Subversion handle ignore patterns. The two systems use the ignore patterns at some different times, and there are slight discrepancies in what the ignore patterns apply to. Also, Subversion does not recognize the use of the ! pattern as a reset back to having no ignore patterns at all.

$ svn status calc

M calc/button.c

? calc/calculator

? calc/data.c

? calc/debug_log

? calc/debug_log.1

? calc/debug_log.2.gz

? calc/debug_log.3.gz

In this example, you have made some property modifications to button.c, but in your working copy you also have some unversioned files: the latest calculator program that you've compiled from your source code, a source file named data.c, and a set of debugging output log files. Now, you know that your build system always results in the calculator program being generated. ^[40] And you know that your test suite always leaves those debugging log files lying around. These facts are true for all working copies, not just your own. And you know that you aren't interested in seeing those things every time you run svn status. So you use svn propedit svn:ignore calc to add some ignore patterns to the calc directory. For example, you might add this as the new value of the svn:ignore property:

calculator

debug_log*

After you've added this property, you will now have a local property modification on the calc directory. But notice what else is different about your svn status output:

$ svn status

M calc

M calc/button.c

Now, all the cruft is missing from the output! Of course, those files are still in your working copy. Subversion is simply not reminding you that they are present and unversioned. And now with all the trivial noise removed from the display, you are left with more interesting items—such as that source code file that you probably forgot to add to version control.

If you want to see the ignored files, you can pass the --no-ignore option to Subversion:

$ svn status --no-ignore

M calc/button.c

I calc/calculator

? calc/data.c

I calc/debug_log

I calc/debug_log.1

I calc/debug_log.2.gz

I calc/debug_log.3.gz

The list of patterns to ignore is also used by svn add and svn import. Both of these operations involve asking Subversion to begin managing some set of files and directories. Rather than force the user to pick and choose which files in a tree she wishes to start versioning, Subversion uses the ignore patterns to determine which files should not be swept into the version control system as part of a larger recursive addition or import operation.

svn:keywords

For example, say you have a document in which you would like to display the last date on which it was modified. You could burden every author of that document to, just before committing their changes, also tweak the part of the document that describes when it was last changed. But sooner or later, someone would forget to do that. Instead simply ask Subversion to perform keyword substitution on the LastChangedDate keyword. You control where the keyword is inserted into your document by placing a keyword anchor at the desired location in the file. This anchor is just a string of text formatted as $KeywordName$.

All keywords are case-sensitive where they appear as anchors in files: you must use the correct capitalization in order for the keyword to be expanded. You should consider the value of the svn:keywords property to be case-sensitive too—certain keyword names will be recognized regardless of case, but this behavior is deprecated.

Subversion defines the list of keywords available for substitution. That list contains the following five keywords, some of which have aliases that you can also use:

Date

This keyword describes the last time the file was known to have been changed in the repository, and looks something like $Date: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $. It may also be specified as LastChangedDate.

This keyword describes the last known revision in which this file changed in the repository, and looks something like $Revision: 144 $. It may also be specified as LastChangedRevision or Rev.

Author

This keyword describes the last known user to change this file in the repository, and looks something like $Author: harry $. It may also be specified as LastChangedBy.

This keyword describes the full URL to the latest version of the file in the repository, and looks something like $HeadURL: http://svn.collab.net/repos/trunk/README $. It may be abbreviated as URL.

Id

This keyword is a compressed combination of the other keywords. Its substitution looks something like $Id: calc.c 148 2002-07-28 21:30:43Z sally $, and is interpreted to mean that the file calc.c was last changed in revision 148 on the evening of July 28, 2002 by the user sally.

To tell Subversion whether or not to substitute keywords on a particular file, we again turn to the property-related subcommands. The svn:keywords property, when set on a versioned file, controls which keywords will be substituted on that file. The value is a space-delimited list of the keyword names or aliases found in the previous table.

For example, say you have a versioned file named weather.txt that looks like this:

Here is the latest report from the front lines.

$LastChangedDate$

$Rev$

With no svn:keywords property set on that file, Subversion will do nothing special. Now, let's enable substitution of the LastChangedDate keyword.

$ svn propset svn:keywords "Date Author" weather.txt

property 'svn:keywords' set on 'weather.txt'

$

Now you have made a local property modification on the weather.txt file. You will see no changes to the file's contents (unless you made some of your own prior to setting the property). Notice that the file contained a keyword anchor for the Rev keyword, yet we did not include that keyword in the property value we set. Subversion will happily ignore requests to substitute keywords that are not present in the file, and will not substitute keywords that are not present in the svn:keywords property value.

The user-visible result of keyword substitution might lead you to think that every version of a file with that feature in use differs from the previous version in at least the area where the keyword anchor was placed. However, this is actually not the case. While checking for local modifications during svn diff, and before transmitting those local modifications during svn commit, Subversion «un-substitutes» any keywords that it previously substituted. The result is that the versions of the file that are stored in the repository contain only the real modifications that users make to the file.

Immediately after you commit this property change, Subversion will update your working file with the new substitute text. Instead of seeing your keyword anchor $LastChangedDate$, you'll see its substituted result. That result also contains the name of the keyword, and continues to be bounded by the dollar sign ($) characters. And as we predicted, the Rev keyword was not substituted because we didn't ask for it to be.

Note also that we set the svn:keywords property to «Date Author» yet the keyword anchor used the alias $LastChangedDate$ and still expanded correctly.

Here is the latest report from the front lines.

$LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $

$Rev$

Cumulus clouds are appearing more frequently as summer approaches.

svn:eol-style

This means that by default, Subversion doesn't pay any attention to the type of end-of-line (EOL) markers used in your files. Unfortunately, different operating system use different tokens to represent the end of a line of text in a file. For example, the usual line ending token used by software on the Windows platform is a pair of ASCII control characters—carriage return (CR) and line feed (LF). Unix software, however, just uses the LF character to denote the end of a line.

Not all of the various tools on these operating systems are prepared to understand files that contain line endings in a format that differs from the native line ending style of the operating system on which they are running. Common results are that Unix programs treat the CR character present in Windows files as a regular character (usually rendered as ^M), and that Windows programs combine all of the lines of a Unix file into one giant line because no carriage return-linefeed (or CRLF) character combination was found to denote the end of line.

This sensitivity to foreign EOL markers can become frustrating for folks who share a file across different operating systems. For example, consider a source code file, and developers that edit this file on both Windows and Unix systems. If all the developers always use tools which preserve the line ending style of the file, no problems occur.

But in practice, many common tools either fail to properly read a file with foreign EOL markers, or they convert the file's line endings to the native style when the file is saved. If the former is true for a developer, he has to use an external conversion utility (such as dos2unix or its companion, unix2dos) to prepare the file for editing. The latter case requires no extra preparation. But both cases result in a file that differs from the original quite literally on every line! Prior to committing his changes, the user has two choices. Either he can use a conversion utility to restore the modified file to the same line ending style that it was in before his edits were made. Or, he can simply commit the file—new EOL markers and all.

The result of scenarios like these include wasted time and unnecessary modifications to committed files. Wasted time is painful enough. But when commits change every line in a file, this complicates the job of determining which of those lines were changed in a non-trivial way. Where was that bug really fixed? On what line was a syntax error introduced?

The solution to this problem is the svn:eol-style property. When this property is set to a valid value, Subversion uses it to determine what special processing to perform on the file so that the file's line ending style isn't flip-flopping with every commit that comes from a different operating system. The valid values are:

native

Note that Subversion will actually store the file in the repository using normalized LF EOL markers regardless of the operating system. This is basically transparent to the user, though.

CRLF

This causes the file to contain CRLF sequences for EOL markers, regardless of the operating system in use.

This causes the file to contain LF characters for EOL markers, regardless of the operating system in use.

CR

This causes the file to contain CR characters for EOL markers, regardless of the operating system in use. This line ending style is not very common. It was used on older Macintosh platforms (on which Subversion doesn't even run).

svn:externals

svn:special

Note: Windows clients don't have symbolic links, and thus ignore any svn:special files coming from a repository that claim to be symbolic links. On Windows, the user ends up with an ordinary versioned file in the working copy.

svn:needs-lock

To learn more about how, when, and why this property should be used, see «Lock Communication».

Automatic Property Setting

Whenever you introduce a file to version control using the svn add or svn import commands, Subversion runs a very basic heuristic to determine if that file consists of human-readable or non-human-readable content. If the latter is the decision made, Subversion will automatically set the svn:mime-type property on that file to application/octet-stream (the generic «this is a collection of bytes» MIME type). Of course, if Subversion guesses incorrectly, or if you wish to set the svn:mime-type property to something more precise—perhaps image/png or application/x-shockwave-flash—you can always remove or edit that property.

Subversion also provides the auto-props feature, which allows you to create mappings of filename patterns to property names and values. These mappings are made in your runtime configuration area. They again affect adds and imports, and not only can override any default MIME type decision made by Subversion during those operations, they can also set additional Subversion or custom properties, too. For example, you might create a mapping that says that any time you add JPEG files—ones that match the pattern *.jpg—Subversion should automatically set the svn:mime-type property on those files to image/jpeg. Or perhaps any files that match *.cpp should have svn:eol-style set to native, and svn:keywords set to Id. Auto-prop support is perhaps the handiest property related tool in the Subversion toolbox. See «Config» for more about configuring that support.