Подстановка ключевых слов

Пока вы редактируете исходные файлы в рабочем каталоге, вы всегда можете узнать их статус с помощью `cvs status' и `cvs log'. Как только вы экспортируете файлы из вашей среды разработки, становится гораздо сложнее узнать, какую ревизию имеют эти файлы.

Для того, чтобы помочь в идентификации файлов, CVS может использовать механизм, известный как подстановка ключевых слов (или замена ключевых слов). Строки вида $ключевое_слово$ и $ключевое_слово:...$ в файле заменяются строками вида $ключевое_слово:значение$ каждый раз, когда вы получаете новую ревизию файла.

Список ключевых слов

Вот список ключевых слов:

$Author$

Имя пользователя, который поместил ревизию в репозиторий.

$Date$

Дата и время (в UTC), когда была зафиксирована ревизия.

$Header$

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

$Id$

Точно так же, как $Header$, только имя RCS-файла указано без полного пути.

$Name$

Имя метки, использованной при извлечении этого файла. Это ключевое слово подставляется, только если при извлечении было явно задано имя метки. Например, при выполнении команды cvs co -r first это ключевое слово заменяется на `Name: first'.

$Locker$

Имя пользователя, который заблокировал эту ревизию (пустое, если файл не заблокирован, как обычно и бывает, если не использовалась команда cvs admin -l).

$Log$

Журнальное сообщение, которое было введено во время фиксации изменений, перед которым идет имя RCS-файла, номер ревизии, имя автора и дата в UTC. Существующие журнальные сообшения не заменяются. Вместо этого, новое журнальное сообщение добавляется после $Log:...$. Каждая новая строка содержит в начале ту же самую строку, которая находится перед ключевым словом $Log$. Например, если в файле находится

  /* Here is what people have been up to:
   *
   * $Log: frob.c,v $
   * Revision 1.1  1997/01/03 14:23:51  joe
   * Add the superfrobnicate option
   *
   */

то перед дополнительными строками, которые добавляются при замене ключевого слова $Log$, будет находиться ` * '. В отличие от предыдущих версий CVS и RCS, префикс комментария из RCS-файла не используется. Ключевое слово $Log$ полезно при накоплении полного журнала изменений в исходном файле, но по нескольким причинам это может привести к определенным проблемам. See section Проблемы с ключевым словом $Log$..

$RCSfile$

Имя RCS-файла без полного пути.

$Revision$

Номер ревизии.

$Source$

Полное имя RCS-файла.

$State$

Состояние, присвоенное ревизии. Состояния могут назначаться с помощью cvs admin -s -- см. section Ключи команды admin.

Использование ключевых слов

Для того, чтобы поместить в файл ключевое слово, вы просто пишете в нём, например, $Id$, а затем фиксируете файл. CVS автоматически заменит ключевое слово во время операции фиксирования.

Обычной практикой является помещение строки $Id$ в исходные файлы, чтобы они оказались в скомпилированных объектных файлах. Например, если вы управляете исходными текстами программы, вы можете создать переменную, в которую при инициализации попадает строка с $Id$. Некоторые компиляторы языка C поддерживают директиву #pragma ident. Система управления документами может обеспечивать способ для передачи этой строки в результирующие файлы.

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

$ ident samp.c
samp.c:
     $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
$ gcc samp.c
$ ident a.out
a.out:
     $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $

SCCS -- еще одна популярная система контроля ревизий. В её состав входит программа what, очень похожая на ident и использующаяся в тех же целях. Во многих местах, где не установлен пакет RCS, стоит SCCS. Так как what ищет последовательность символов @(#), то можно довольно просто вставлять ключевые слова, которые обнаруживаются обеими программами. Просто поместите перед ключевым словом в стиле RCS волшебную фразу в стиле SCCS, например:

static char *id="@(#) $Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";

Как избежать подстановки

Подстановка ключевых слов имеет свои недостатки. Иногда бывает нужно, чтобы строка `$'Author$ появилась в файле без того, чтобы CVS интерпретировала её как ключевое слово и заменила на что-нибудь типа `$'Author: ceder $.

К сожалению, нельзя выборочно отключить подстановку ключевых слов. Можно лишь использовать ключ командной строки `-ko' (see section Режимы подстановки), чтобы полностью выключить эту подстановку.

Во многих случаях вам нужно избежать использования ключевых слов в исходном тексте, даже несмотря на то, что они появятся в конечном продукте. Например, исходный текст этого руководства содержит `$@asis{}Author$' везде, где должна появиться строка `$'Author$. При использовании nroff и troff можно поместить в ключевое слово нулевой символ \&, чтобы добиться подобного эффекта.

Режимы подстановки

Вместе с каждым файлом хранится его режим подстановки ключевых слов по умолчанию, и каждая копия файла в рабочем каталоге также имеет режим подстановки. Режим по умолчанию задается с помощью ключа `-k' команд cvs add и cvs admin; режим в рабочем каталоге задается с помощью ключей `-k' и `-A' команд cvs checkout и cvs update. Команда cvs diff также имеет ключ `-k'. Некоторые примеры приведены в section Обработка двоичных файлов.

Доступные режимы таковы:

`-kkv'

Генерировать строки из ключевых слов стандартным образом, то есть из ключевого слова Revision получается $Revision: 5.7 $.

`-kkvl'

Подобно `-kkv', но только всегда указывается имя заблокировавшего пользователя, если данная ревизия в настоящий момент заблокирована. Имя блокировщика имеет смысл только если используется cvs admin -l.

`-kk'

Генерировать только имена ключевых слов и опускать их значения. Например, для ключевого слова Revision получается строка $Revision$, а не $Revision: 5.7 $. Этот ключ полезен для игнорирования изменений, возникающих из-за ключевых слов, при сравнении разных ревизий файла.

`-ko'

Генерирует старую строку, присутствовавшую в рабочем файле перед тем, как он был зафиксирован. Например, для ключевого слова Revision генерируется строка $Revision: 1.1 $ вместо $Revision: 5.7 $, если она была записана именно так, когда файл был помещен в репозиторий.

`-kb'

Подобно `-ko', но также предотвращает преобразование символов конца строк между канонической формой, в которой они хранятся в репозитории (только символ перевода строки), и формой, принятой в используемой операционной системе. Для UNIX-подобных систем, в которых для завершения строк используется символ перевода строки, этот режим совпадает с `-ko'. Дополнительная информация о двоичных файлах находится в section Обработка двоичных файлов.

`-kv'

Генерирует только значения ключевых строк. Например, для ключевого слова Revision генерируется строка 5.7 вместо $Revision: 5.7 $. Это может помочь при генерации файлов на языках программирования, в которых сложно извлечь из строки разделители ключевых слов, такие как как $Revision: $. Однако, дальнейшая подстановка ключевых слов не может быть осуществлена, когда удалены ключевые слова, поэтому этот ключ нужно использовать осторожно. Часто бывает полезно использовать `-kv' совместно с командой cvs export -- see section Команда export: экспортировать исходные тексты. Помните только, что этот ключ некорректно экспортирует двоичные файлы.

Проблемы с ключевым словом $Log$.

Ключевое слово $Log$ довольно-таки спорно. Пока вы работаете над проектом, информация легко доступна даже без использования ключевого слова $Log$: просто вызовите cvs log. Когда вы экспортируете файл, информация об его истории в любом случае практически бесполезна.

Более серьёзным обстоятельством является то, что CVS не слишком хорошо справляется с пунктами $Log$, когда ветка объединяется с основным стволом. В результате такого объединения часто возникают конфликты.

Люди часто стараются "исправить" журнальные записи в файле, исправляя орфографические и даже фактические ошибки. В результате информация от cvs log не совпадает с информацией в файле. Это может стать (а может и не стать) проблемой при реальной работе.

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

Go to the first, previous, next, last section, table of contents.