CO(1)
КОМАНДЫ ПОЛЬЗОВАТЕЛЯ

НАЗВАНИЕ
co - востребование из RCS архива определенной версии файла

СИНТАКСИС

co [флаги] имя-файла ...

ОПИСАНИЕ
Команда co получает из архивного файла копию некоторой версии файла и помещает ее в рабочий файл.

Полное имя файла, содержащее архивный суффикс, соответствует архивному файлу, все прочие считаются рабочими файлами. О соответствии имен файлов, см. ci(1) .

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

Востребуемая версия может быть задана с помощью флагов по номеру и ветви, времени регистрации, автору и статусу. Если (не)примененные флаги определяют несколько версий, то извлекается последняя версия главной ветви (или ветви, используемой по умолчанию, см. флаг -b команды rcs(1) ). Номер версии и/или ветви может бать использован с любым из флагов -f, -I, -l, -M, -p, -q, -r или -u.

Флаги -d (дата), -s (статус), и -w (автор) выберут версию из ветви, заданной версиями -f, ..., -u; а если они не заданы, то из ветви, используемой по умолчанию.

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

ФЛАГИ

-r[rev]

Востребует последнюю версию из тех, чей номер меньше или равен rev . Если rev задает номер ветви, то последнюю версию на этой ветви из тех, чей номер меньше или равен rev . Если rev опущен, то извлекается последняя версия ветви, используемой по умолчанию (см. опцию -b команды rcs(1) ). Если в качестве rev использован символ $, команда co определит версию, подлежащую возврату по ключевым словам, содержащимся в идентификационных маркерах архива. Иначе версия может быть определена последовательностью из одного или более числовых или символьных полей, разделенных точками. Если эта последовательность начинается с точки, то она добавляется к ветви, используемой по умолчанию (обычно, главной). Если эта последовательность задает ветвь и заканчивается точкой, то к ней добавляется номер последней версии на этой ветви. Численный эквивалент символьного поля задается флагом -n команд ci(1) и rcs(1) .

-l[rev]

Делает то же, что и флаг -r, но дополнительно бронирует для пользователя востребованную версию.

-u[rev]

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

-f[rev]

Безусловно востребует версию, затирая, если нужно рабочий файл. Обычно используется в паре с флагом -q. См. ниже АТРИБУТЫ ФАЙЛОВ.

-kkv

Подставляет значения ключевых символов (например, $Revision: 5.13 $) в идентификационные маркеры (здесь: $Revision$ ). Флаг включен по умолчанию. Имя пользователя, забронировавшего файл, подставляется в значения ключевых символов Header, Id, и Locker только тогда, когда файл действительно забронирован, например, командами ci -l или co -l .

-kkvl

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

-kk

Подставляет в идентификационные маркеры сами ключевые символы, но не их значения. См. раздел АВТОМАТИЧЕСКАЯ ИДЕНТИФИКАЦИЯ. Например, ключевое слово Revision порождает идентификационную строку $Revision$ вместо стандартного $Revision: 5.13 $.

Используется чтобы подавить сообщения о различающихся строках, вызванные подстановкой ключевых символов, если нужно сравнить две версии. Регистрационные же записи после ключевого слова $Log$ подставляются, даже если задан флаг -kk, поскольку их использование осмыслено даже в такой ситуации, а тем более, при объединении изменений, внесенных в две ветви.

-ko

Порождает идентификационные строки, существовавшие в рабочем файле непосредственно перед его регистрацией. Например, Для ключевого слова Revision породит идентификационную строку $Revision: 1.1 $ вместо строки $Revision: 5.13 $ , если она именно так и выглядела до регистрации. Используется для форматов файлов или систем, которые не приемлют изменений в идентификационных маркерах, происходящих вследствие подстановок значений ключевых символов, или для подавления нежелательных эффектов. Так, читаемый Вами файл, извлечен из архива именно с этим флагом из-за обилия ключевых символов, которые нельзя изменять.

-kb

Делает то же, что и флаг -kb, но ввод-вывод осуществляется не в текстовом, а в двоичном режиме. Для операционной системы типа Posix или Unix это бессмысленно, но для систем типа DOS, для инициализации архива, предназначенного для хранения двоичных файлов нужно использовать команду rcs -i -kb . Команда же rcsmerge(1) просто отказывается работать с флагом -kb.

-kv

Подставляет в идентификационные маркеры сами значения ключевых символов, но не сами ключевые символы. См. раздел АВТОМАТИЧЕСКАЯ ИДЕНТИФИКАЦИЯ. Например, ключевое слово Revision порождает идентификационную строку 5.13 вместо стандартного $Revision: 5.13 $.

Используется чтобы убрать из файла ключевые слова типа $Revision: $ для языков, где это невозможно сделать средствами самого языка, например, включив его в комментарий. Однако, удаленные ключевые слова, не могут быть восстановлены автоматически. Опасность потери ключевых слов не позволяет использовать флаг -kv вместе с флагом -l, и потому атрибут права владельца на изменение рабочего файла отменяется. Для редактирования, востребуйте файл повторно без -kv.

-p[rev]

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

-q[rev]

Все сообщения подавляются. Используется в фоновом режиме.

-I[rev]

Диалоговый режим; пользователю посылаются приглашения для ввода и задаются вопросы, даже если ввод осуществляется не с терминала.

-ddate

Востребует последнюю из версий заданной ветви, время и дата регистрации которой не позже, чем date . Формат задания почти свободный. Часовой пояс LT задает местное время. Правильно распознаются почти все аббревиатуры на английском языке. Пусть, например, текущее время 8 часов вечера, 11 января 1990, в Тихоокеанском часовом поясе США (PST), что на 8 часов позже, чем в Гринвиче (GMT или UTC -- Coordinated Universal Time). Тогда следующие форматы эквивалентны:

8:00 pm lt                     по умолчанию -- сегодня

4:00 AM, Jan. 12, 1990

1990-01-12 04:00:00+00         стандарт ISO 8601 (UTC)

1990-01-11 20:00:00-08              ISO 8601 (местное)

1990/01/12 04:00:00             стандартный формат RCS

Thu Jan 11 20:00:00 1990 LT       выдача ctime(3) + LT

Thu Jan 11 20:00:00 PST 1990            выдача date(1)

Fri Jan 12 04:00:00 GMT 1990

Thu, 11 Jan 1990 20:00:00 -0800       Internet RFC 822

12-January-1990, 04:00 WET

Для большинства полей существуют значения, используемые по умолчанию. Часовой пояс -- UTC, но флаг -z может это изменить. Порядок в значениях по умолчанию: год, месяц, день, час, секунда (начиная с более крупных единиц -"big endian" формат). Если со флагом не заданы какие-то единицы, то они, начиная с самых крупных до первого заданного поля, полагаются равными их значению в текущем времени в заданном часовом поясе; остальные полагаются равными их минимальному значению. Например, если не задана флаг -z, то в примере выше, флаг -d20,10:30 равносилен -d"1990/01/20 10:30:00". Обратите внимание на использование кавычек или обратной косой черты, если строка с датой содержит пробел.

-M[rev]

Присвоить атрибуту времени последнего изменения рабочего файла время регистрации востребованной версии. Используйте эту возможность с осторожностью: построение (в частности, компиляция) будет подавлено , если проводилось построение со старой версией после регистрации новой версии. См. make(1).

-sstate

Востребует из заданной ветви последнюю из версий со статусом state .

-T

Сохраняет дату и время последнего изменения рабочего файла даже если в него была занесена отметка о бронировании. Такое поведение флага вводит в заблуждению команду make(1) и, потому необходима осторожность. Флаг -T позволяет избежать ненужных построений (компиляций), но он может подавить их и тогда, когда изменение идентификационных маркеров вследствие бронирования существено для результата построения.

-w[login]

Востребует последнюю из версий заданной ветви, зарегистрированную пользователем login . Если имя login опущено, подразумевается имя вызвавшего пользователя.

-jjoinlist

Создает новую версию, применив к первой версии rev1 списка joinlist изменения сделанные для того, чтобы получить из второй версии rev2 третью rev3 . Флаг стал рудиментарным после включения в пакет RCS команды rcsmerge(1) , но сохранен для совместимости с предыдущими версиями

Список joinlist составлен из пар вида rev2:rev3, разделенных запятыми, где rev2 и rev3 это номера (числовые или символические) версий. Первой в этом списке задается версия rev1 которая определяет версию к которой будут применяться остальные флаги (-f, ..., -w). Если пар более одной, то для каждой последующей пары, роль rev1 будет исполнять результат применения команды к предыдущей паре.

То что к первой версии применяются лишь изменения, ведущие от второй версии к третьей, имеет несколько следствий. Во-первых, изменения, ведущие от rev1 к rev2 игнорируются. Во-вторых, эта операция перестановочна по отношению к версиям rev1 и rev3 . В-третьих, эта операция объединяет изменения ведущие от rev2 к rev1 с изменениями ведущие от rev2 к rev3. Используется в двух случаях.

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

Пусть номера версий на одной ветви удовлетворяют условию rev1 < rev2 < rev3 . Тогда этот флаг отменит изменения сделанные в файле в период работы над rev2 . Это позволяет исключить ошибки, внесенные на ранних стадиях проекта, не переделывая заново работы, сделанной на более поздних стадиях.

Если изменения ведущие от rev2 к rev1 и изменения ведущие от rev2 к rev3 были применены к одной и той же части файла, программа выдаст сообщение так, как описано в merge(1).

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

-V

Посылает номер версии RCS в стандартный вывод.

-Vn

Имитирует работу RCS версии n, n=3,4,5. Используется при обмене файлов с корреспондентами, использующими старые версии программ. Для того, чтобы определить, какую версию RCS использует ваш партнер, используйте rcs -V; если это не сработало, вызовите rlog для архивного файла. Если первые стоки выдачи не содержат слова branch (ветвь): то это версия 3; если в формате даты для года использованы две цифры, это версия 4; в остальных случаях это 5 версия. При эмуляции версии 3 архив теряет свойство содержать ветви, для 4 версии или более ранних отметка времени может измениться на величину до 13 часов, меняется формат даты на yy/mm/dd и форматы идентификационных маркеров содержат иные разделители.

-xsuffixes

Использовать суффиксы suffixes для определения архивных файлов RCS . См. ci(1) .

-zzone

Задает формат даты и времени и часовой пояс при подстановке ключевых слов в идентификационные маркеры в рабочем файле со флагом -ddate . Параметр zone должен быть либо пуст, либо являться численным значением отклонения от Всемирного Времени (UTC) , либо специальной строкой LT, задающей использование местного времени. По умолчанию, или опущенный параметр zone , задают использование Всемирного Времени с использованием косой черты в качестве разделителя полей для даты (см. пример). В остальных случаях используется стандарт ISO 8601. Например, пусть текущее время 8 часов вечера, 11 января 1990, в Тихоокеанском часовом поясе США (что на 8 часов позже, чем в Гринвиче). Тогда для подстановок будет использовано

флаг      формат времени

-z        1990/01/12 04:00:00       (по умолчанию)

-zLT      1990-01-11 20:00:00-08

-z+05:30  1990-01-12 09:30:00+05:30

Флаг -z влияет только на маркеры, и не меняет формата даты и времени в архивном файле, которые всегда задается во Всемирном Времени.

АВТОМАТИЧЕСКАЯ ИДЕНТИФИКАЦИЯ
Если в тексте файла встречаются выражения вида $keyword$ или $keyword:...$ , где keyword одно из описанных ниже ключевых слов, то они заменяются идентификационными маркерами -строками вида $keyword:значение$ . Обычно их вставляют в комментарии или строковые переменные программ -- для распознавания версий.

Как правило, начальная версия содержит идентификационные маркеры в виде $keyword$. Подстановка значения происходит при востребовании: команда co заменит такой маркер маркером вида $keyword:значение$ . В случае, если регистрируемый рабочий файл уже содержит значения ключевых слов, то старые значения хранятся в архиве и будут изменены только при востребовании. (Новые значения тоже хранятся, но в другом виде.) Таким образом, обновление идентификационных маркеров совершается командой co автоматически, но флаг -k может изменить такое поведение.

КЛЮЧЕВЫЕ СЛОВА И ИХ ЗНАЧЕНИЯ:

$Author$

Имя (login name) пользователя зарегистрировавшего данную версию.

$Date$

Дата и время регистрации версии. Флаг -zzone добавит числовое значение часового пояса, по умолчанию используется Всемирное Время.

$Header$

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

$Id$

То же, что и $Header$, но имя файла не содержит путь.

$Locker$

Имя пользователя, забронировавшего версию для внесения изменений. Пустая строка, если файл не забронирован.

$Log$

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

Подстрока, стоящая перед символом $Log$ , добавляется перед каждой строкой регистрационных записей. Например, если эта строка выглядит как " // $Log: tan.cc $" , то перед каждой строкой регистрационных записей будет добавлено " // " , что удобно для языков программирования, где комментарии продолжаются до конца строки. Для других языков регистрационные записи помещают внутрь многострочного комментария. Так, для языка C , регистрационные записи превратятся в канонический комментарий, отмеченый звездочками, если при инициализации архива оформить его в виде

/*

 * $Log$

 */

Для совместимости с прежними версиями, для префиксов вида /* или (* , возможно, с дополнительными пробелами, внутренние строки содержат пробел вместо / или (; однако, в дальнейших версиях, это свойство не будет сохранено.

$Name$

Символическое имя, использованное при извлечении файла из архива. Например, co -rJoe породит $Name: Joe $ . Просто co породит просто $Name: $.

$RCSfile$

Имя файла, без пути.

$Revision$

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

$Source$

Полное имя файла с абсолютным заданием пути.

$State$

Статус заданный флагом -s команд rcs(1) или ci(1).

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

символ   представление

tab      \t

newline  \n

space    \040

$        \044

\        \\

АТРИБУТЫ ФАЙЛОВ
Рабочий файл наследует все разрешения на чтение и выполнение от архивного файла. Разрешение на изменение файла владельцу дается всегда, кроме двух случаев: либо был использован флаг -kv либо файл не забронирован никем для внесения изменений при строгой проверке бронирования (см. rcs(1)).

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

ИМЕНА ФАЙЛОВ
Команда co ищет файлы так же, как и команда ci(1) , за исключением того, что ей не нужно читать рабочий файл, если номер версии не задан символом $ .

ПЕРЕМЕННЫЕ СРЕДЫ

LOGNAME

Имя пользователя. В UNIX задано автоматически, в MS-DOS требуется задать явно командой

set LOGNAME=имя-пользователя

TZ

Часовой пояс. В UNIX задан автоматически, в MS-DOS требуется задать явно командой set.

RCSINIT

Список флагов используемых со всеми командами системы отслеживания версий RCS. Не забудьте, что необходимы меры для того, чтобы пробелы между флагами не были обработаны командным интерпретатором преждевременно, защищайте их, например, кавычками. См. ci(1) .

СООБЩЕНИЯ
Для каждой востребуемой версии каждого файла команда co печатает имя архивного файла, имя рабочего файла и номер извлекаемой версии. Возвращает операционной системе 0 тогда и только тогда, когда все операции завершились успешно.

СМ. ТАКЖЕ
rcsintro(1), ci(1), ctime(3), date(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), rcsmerge(1), rlog(1), rcsfile(5)

Walter F. Tichy, RCS--A System for Version Control, Software--Practice & Experience 15, 7 (July 1985), 637-654.
Copyright (C) Walter F. Tichy, Paul Eggert.

ОГРАНИЧЕНИЯ
Системные (жесткие) линки к рабочим и архивным файлам не сохраняются. См. ci(1) ВРЕМЕННЫЕ ФАЙЛЫ И ЛИНКИ.

Не существует средства подавить подстановку значений в ключевые слова средствами RCS кроме иного их написания. Для текстов, используемых командами nroff и troff, например, это достигается помещением в ключевое слово нулевого символа \&.