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

НАЗВАНИЕ
ci - регистрация файла в системе отслеживания версий RCS

СИНТАКСИС

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

ОПИСАНИЕ
Команда ci записывает (регистрирует) новую версию файла в архив. Если путь к файлу содержит каталог RCS или принятый в системе архивный суффикс (детали см. ниже в разделе ИМЕНА ФАЙЛОВ), то он считается архивным файлом, во всех остальных случаях предполагается, что указан рабочий файл, содержащий новейшую версию. Команда ci помещает содержимое рабочего файла в соответствующий архивный (RCS) файл. Если задано имя только одного рабочего файла, она сначала ищет архив в подкаталоге RCS , затем, в каталоге с рабочим файлом, затем, в текущем каталоге; если задано имя только одного архивного файла, она сначала ищет рабочий файл в текущем каталоге.

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

Если не задан флаг -f , команда ci проверяет, действительно ли регистрируемая версия отличается от предыдущей, и если нет, то результат будет такой же, будто команда была применена к предыдущей версии, будет удален файл, снято бронирование, а номер текущей версии не увеличится; ci -l сохранит, а ci -u отменит бронирование, так же, как если бы были исполнены команды co -l или co -u; рабочий файл останется на месте, а номер версии не изменится. В таком случае, если изменений не было внесено, флаги -n и -s относятся к предыдущей версии.

При внесении изменений, ci запрашивает регистрационную запись (log message). Эта запись должна отражать суть внесенных изменений; ее концом считается символ конца файла (<Ctrl-D> в UNIX) или строка, содержащая единственный символ -- точку (как в Mail). Если одной командой регистрируются несколько файлов, то предлагается возможность повторно использовать (reuse) регистрационную запись внесенную в предыдущий архив. Если свой ввод программа получает не с терминала (от другой программы или из командного файла), то запрос подавляется, и для всех файлов, регистрируемых одной командой, используется одна регистрационная запись. См. флаг -m.

Если архивный (RCS) файл не существует, ci создаст его и, по умолчанию задаст номер 1.1 . Список лиц имеющих доступ к к файлу изначально пуст, а вместо регистрационной записи, запрашивается описание файла. (См. флаг -t).

Номер rev регистрируемой версии может быть задан с любым из флагов -f, -i, -I, -j, -k, -l, -M, -q, -r или -u.

Номер rev может быть символьным, числовым или смешанным, но входящие в него символические имена должны быть уже определены; см. флаги -n и -N о присваивании имен при регистрации. Если rev = $ , то ci определяет номер версии по идентификационным маркерам в рабочем файле.

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

Номер rev регистрируемой версии либо должен быть больше, чем номер последней версии в соответствующей ветви, либо он должен начинать новую ветвь.

Если rev является номером ветви, а не версии, то файл ставится в конец этой ветви, а номер версии получается увеличением на единицу номера версии находящейся на вершине этой ветви. Если rev задает несуществующую ветвь, то эта ветвь создается, с первой версией под номером rev.1.

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

Если ни rev не задано, ни версии не забронированы, но пользователь является владельцем файла, и используется нестрогое бронирование, то новая версия добавляется к ветви, определяемой по умолчанию (обычно -- главной; см. флаг -b команды rcs(1) ).

Замечание: в главной ветви все версии получены добавлением в конец, как в магазине (стеке), и не могут быть вставлены в середину.

ФЛАГИ

-rrev
Зарегистрировать под номером версии rev.

-r
Для всех прочих команд RCS , флаг -r без номера по умолчанию задает наименьший возможный номер версии. Для команды ci такой эффект (номер на единицу больший последней зарегистрированной версии) достигается отсутствием флага, а -r используется для того, чтобы восстановить поведение команды по умолчанию в отношении бронирования и удаления файла. Нужно это для того, чтобы отменить действие флагов -l и -u заданное командным файлом, псевдонимом или переменными среды.

-l[rev]
Действует так же, как -r , после которой была исполнена команда co -l для той же версии. Это означает, что новая версия файла восстанавливается в рабочий файл и сразу же бронируется. Все маркеры обновляются. Используется в случае, когда нужно сохранить промежуточный результат и продолжить работу с файлом.

-u[rev]
Действует так же, как -l , версия не бронируется. Все маркеры обновляются. Используется в случае, когда работа с файлом закончена, но нужно сохранить доступ для чтения рабочей версии.

Три флага: -l , -r без номера, и -u , взаимно исключают друг друга, и каждый последующий отменяет предыдущий без сообщения. Пусть, например, флаг -r задан как параметр командному файлу или псевдониму, который использует ci -u . Тогда в результате подстановки получится ci -u -r что равносильно ci -r потому, что -r без номера отменит -u .

-f[rev]
Безусловно регистрирует версию под новым номером, даже в случае, отсутствия фактических изменений.

-k[rev]
Просматривает идентификационные маркеры в рабочем файле, чтобы определить его версию, дату создания, статус и автора (см. co(1) ), приписывает их регистрируемой версии, вместо того, чтобы определять их по архиву и системным часам. При этом генерируется регистрационная запись, отмечающая действительное время и регистрирующего пользователя. Применяется при рассылке документов или текстов программ. Для сохранения авторских данных, в т.ч. номера версии и времени создания, во всех депозитариях файл нужно регистрировать с флагом -k . Следует заметить, что и значения ключевых слов и регистрационная запись могут быть изменены флагами -d , -m , -s , -w и любой другой, содержащей номер версии в явном виде.

-q[rev]
Подавляет сообщения. Если не задан флаг -f , и файл не отличается от последней зарегистрированной версии, то регистрации не происходит. Используется в командных файлах.

-i[rev]
Регистрация с инициализацией архива. Выдает сообщение об ошибке, если архивный файл уже существует. Используется при несоответствии быстродействия подсистем. Также, позволяет избежать присваивания одного имени разным документам.

-j[rev]
Регистрация без инициализации архива. Выдает сообщение об ошибке, если архивного файла нет. См. флаг -i .

-I[rev]
Интерактивный режим. Выдаются сообщения и запросы, даже если ввод осуществляется не с клавиатуры.

-d[date]
Задает дату и время для регистрационной отметки в архиве. Формат -- свободный, как указан в co(1). Используется для задания фиктивной даты с флагом -k , если в рабочем файле не указана дата. Если дата не указана, но флаг задан, используется время последнего изменения файла.

-M[rev]
Сохраняет время последнего изменения файла (как атрибут этого файла). Например, команда ci -d -M -u f не меняет время последнего изменения f , даже если его содержание изменилось после подстановки значений ключевых слов. Такое поведение флага вводит в заблуждению команду make(1) и, потому необходима осторожность.

-mmsg
Использовать строку msg в качестве регистрационной записи. По соглашению, регистрационные записи, начинающиеся с # , являются комментариями и игнорируются программами типа отслеживания версий в emacs(1) . Регистрационные записи, начинающиеся с {некий-признак} (и пробелом после) предназначены для группировки в истории изменений файла и могут служить признаком для группировки в истории системы, даже если относятся к разным файлам. Сам символ {некий-признак} не является частью регистрационной записи. Ср. -t .

-nname
Присваивает номер регистрируемой версии символическому имени name . Если это имя связано с другой версией того же файла, выдает сообщение об ошибке.

-Nname
То же, что и -n , но вместо сообщения об ошибке отменяет старое значение name.

-sstate
Придает регистрируемой версии статус state . Статус по умолчанию -- Exp .

-tfile
Использовать содержимое файла file в качестве описания регистрируемого файла. Ограничение: минус не может быть первым символом в имени file.

-t-string
Использовать строку string в качестве описания регистрируемого файла.

Флаг -t в обеих формах имеет смысл только при инициализации архива, при регистрации последующих версий игнорируется. Ср. -m .

Если при инициализации архива флаг -t не задан , то команда ci потребует ввести со стандартного ввода описание файла (что он из себя представляет, зачем нужен и т.п.; эта запись будет относиться ко всем версиям), ее концом считается символ конца файла (<Ctrl-D> в UNIX) или строка, содержащая единственный символ -- точку. Если при этом возможно взаимодействие с пользователем, программа выдаст приглашение ко вводу.

Для совместимости с предыдущими версиями, -t без параметра игнорируется.

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

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

Используйте эту возможность с осторожностью: она может подавить построение (в частности, компиляцию), если с одним архивным файлом связано несколько рабочих. Например, пусть архивный файл был последний раз изменен в 13:00, Ваша личная копия была изменена в 14:00, копия общего пользования в каталоге над RCS была извлечена в 15:00, а сейчас 16:00. Вы делаете символический линк общего каталога RCS с архивным файлом в подкаталог RCS вашего рабочего каталога и вызываете команду ci -d -T . Это устанавливает время изменения архива как атрибут файла равным 14:00, а не 16:00. В результате, программа make(1) , если она работает с архивом, будет облыжно считать, что другая рабочая копия новее, чем архив (обычно, она должна при построении системы заменить старый рабочий файл последней версией).

-wlogin
Использовать для отметки об авторе при регистрации имя login вместо имени пользователя. Используется при регистрации от чужого имени или с флагом -k , если RCS не может самостоятельно определить автора.

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

-Vn
Имитирует поведение версии n комплекса программ RCS . См. co(1) .

-xsuffixes
Задает суффикс, добавляемый к имени архивного файла. Если архивный суффикс непуст, то архивом считается любое подходящее имя файла, на него заканчивающееся. Пустому суффиксу соответствует путь к архиву вида RCS/path или path1/RCS/path2 . Флаг -x может задавать не один, а несколько суффиксов, разделенных косой чертой. Например, -x,v/ задаст два архивных суффикса: ,v и пустой суффикс. Если заданы два или более суффиксов, команда ci пытается их использовать для поиска архива поочередно (см. ИМЕНА ФАЙЛОВ). Первый из найденных по такому критерию файлов и считается архивом. Если архив не найден, но может быть создан, он создается исходя из того же критерия.

Архивный суффикс, используемый по умолчанию зависит от операционной системы и равен ,v , если операционная система, как UNIX, поддерживает запятые в имени файла; и пустой суффикс (т.е. имя архива отличается только каталогом) , если -- нет. Чаще всего архив помещают в подкаталог с именем RCS.

-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 влияет только на маркеры, и не меняет формата даты и времени в архивном файле, которые всегда задается во Всемирном Времени.

ИМЕНА ФАЙЛОВ.
Пара рабочий файл -- архив может быть задана тремя способами (СМ. ТАКЖЕ ПРИМЕРЫ).

1. Заданы оба файла -- и рабочий файл и архив, причем в любом порядке. Система отслеживания версий RCS распознает это, если архивный файл задан в виде path1/workfileX , а рабочий файл в виде path2/workfile , где path1/ и path2/ -абсолютные или относительные пути (возможно различные или пустые) к файлам; workfile -- имя файла, а X принятый в RCS архивный суффикс. Если этот суффикс X пуст, path1/ должен либо быть относительным и начинаться с RCS/ или должен включать каталог /RCS/ .
2. Задан только архивный файл. Тогда система отслеживания версий RCS считает, что рабочий файл должен находиться в текущем каталоге, а его имя получается из имени архива отбрасыванием части пути path1/ и архивного суффикса.
3. Задан только рабочий файл. Тогда система отслеживания версий RCS считает, что имя архивного файла должно получаться из имени рабочего добавлением архивного суффикса и, возможно, подкаталога /RCS/ . Система отслеживания версий ищет архив поочередно, до первого успеха, пробуя принятые в RCS суффиксы и комбинации path2/RCS/workfileX и (если архив не найден и X -- непустой суффикс) path2/workfileX.

Если архивный файл задан в 1) или 2) без указания пути, то система отслеживания версий RCS ищет его сначала в подкаталоге ./RCS , а затем, в текущем каталоге.

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

ПРИМЕРЫ
Допустим, в качестве архивного суффикса RCS использует ,v . В текущем каталоге находятся рабочий файл io.c и подкаталог RCS с архивным файлом io.c,v . Тогда любая из приведенных ниже команд регистрирует файл io.c в архиве RCS/io.c,v в качестве последней версии и удаляет файл io.c.

ci  io.c;    ci  RCS/io.c,v;   ci  io.c,v;

ci  io.c  RCS/io.c,v;    ci  io.c  io.c,v;

ci  RCS/io.c,v  io.c;    ci  io.c,v  io.c;

Если же используется пустой суффикс, в аналогичной ситуации возможностей меньше:

ci  io.c;    ci  RCS/io.c;

ci  io.c  RCS/io.c;

ci  RCS/io.c  io.c;

АТРИБУТЫ ФАЙЛОВ
Архивный файл, создаваемый командой ci наследует от рабочего разрешения для пользователей и групп на чтение и выполнение. Если архив уже существовал, то его атрибуты сохраняются. Разрешение же на запись в него отменяется всегда, когда файл не забронирован флагом -l.

ВРЕМЕННЫЕ ФАЙЛЫ И ЛИНКИ
При работе программы в каталоге с рабочим файлом и системном каталоге для временных файлов (см. ПЕРЕМЕННЫЕ СРЕДЫ : TMPDIR ) создаются временные промежуточные файлы. В каталоге с архивными файлами создаются сигнальные файлы, имя которых начинается с первого символа архивного суффикса, а если суффикс пуст, то -- заканчивается символом подчеркивания. Следовательно, не стоит выбирать архивный суффикс начинающийся с буквы или цифры или называть рабочий файл именем оканчивающимся символом подчеркивания.

Команда ci не меняет рабочий или архивный файл физически, а создает новый и исправляет указатель на него в каталоге. Поэтому символические линки на файлы в системе RCS сохраняются, а системные -- нет.

Программы системы отслеживания версий RCS проверяют право логического (effective) пользователя (т.е. владельца процесса, вызвавшего соответствующую программу) на поиск и запись в архивном каталоге и запись в архивный файл. Относительно права читать архивный и рабочий файлы, вести поиск и записывать в каталог с рабочим файлом, проверяется физический (real) пользователь (владелец процесса, соответствующего исполняемой программе). Не все операционные системы позволяют программам свободно переключать свои права доступа между привилегиями логического и физического пользователя. В таком случае, для доступа используется имя логического пользователя. Впрочем, чтобы имя физического пользователя не совпадало с именем логического, нужно, чтобы у используемых копий программ ci и co было право на использование привилегий их владельца (атрибут файла s), а не только привилегий вызывающего пользователя. В следующем разделе показано, как это использовать для дополнительного обеспечения безопасности информации.

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

ДОПОЛНИТЕЛЬНЫЕ МЕРЫ БЕЗОПАСНОСТИ
Для предотвращения случайного или злонамеренного удаления версий и реальной возможности возложить ответственность за них на администратора системы отслеживания версий RCS , могут быть приняты следующие меры.

• Проверьте, поддерживает ли Ваша операционная система системный вызов setuid в полном объеме. Проконсультируйтесь у специалиста или проэкспериментируйте с RCS . Идеально, если системный вызов seteuid Вашей операционной системы соответствует стандарту Posix 1003.1a Draft 5, потому, что это означает, что RCS сможет легко переключать права доступа логического и физического пользователей, даже если физическим пользователем является root . Приемлемо, если операционная система поддерживает информацию о бывшем владельце ( saved setuid ) (свойство {_POSIX_SAVED_IDS} стандарта Posix 1003.1-1990 ); тогда проблемы возникают, только если физический пользователь -root . Следует заметить, что при ошибке, вызванной системным вызовом setuid , команды RCS аварийно завершают работу.
• Назначьте пользователя A на должность администратора системы отслеживания версий. Только A должен иметь право выполнять команду rcs для общих архивных файлов. A не должен быть привилегированным пользователем (таким, как root или uucp) . Группы пользователей испытывающих недоверие друг к другу должны назначать разных администраторов.
• Пусть путь каталог B предназначен для исполняемых файлов системы RCS для данной группы.
• Сделайте так, чтобы владельцем команд в каталоге B был A и задайте атрибут, передающий программам права доступа, принадлежащие A . Например,

  
  mkdir  B
  
  cp  D/c[io]  B
  
  chmod  go-w,u+s  B/c[io]
  
  

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

  
  PATH=B:$PATH;
  
  export  PATH         # обычный командный интерпретатор
  
  
  
  set  path=(B  $path) # командный интерпретатор типа csh
  
  

• Создайте каталог(и) R для рабочих и R/RCS для архивных файлов с правом на запись в каталоги только для A .

  
  mkdir  R
  
  mkdir  R/RCS
  
  chmod  go-w  R  R/RCS
  
  

• Если нужно закрыть архивы от просмотра посторонними, объедините пользователей вместе с A в группу G , и пусть A закроет каталоги для просмотра и чтения.

  
  chgrp  G  R
  
  chmod  g-w,o-rwx  R
  
  

• Пусть A скопирует все старые файлы, подлежащие контролю в эти каталоги, что запишет его их владельцем.
• Список лиц имеющих доступ к файлу хранится непосредственно в архивном файле и ограничивает круг лиц, имеющих право изменять архив средствами системы отслеживания версий RCS (помимо RCS изменять архив могут только A и root). По умолчанию он пуст, а это значит, что регистрировать новые версии может всякий, кто может читать архивный файл (рабочий файл может находиться и не в R ). Если Вы хотите ограничить этот круг, пусть A вызовет команду rcs со флагом -a для соответствующего файла. См. rcs(1). В частности,

  
  rcs -e -aA
  
  

  Оставляет это право только за A (но еще не бронирует сам файл).
• Пусть A проинициализирует все архивные файлы командой rcs со флагом -i до регистрации первой версии другими представителями группы, добавив флаг -a , если нужно ограничить доступ к архиву.
• Задайте возможность использования прав доступа владельца (установкой атрибута s ) только для трех команд: ci, co и rcsclean; не давайте этого права команде rcs и остальным программам RCS.
• Не присваивайте атрибут s другим программам. Системный вызов setuid гораздо сложнее, чем кажется, а будучи присвоен командам, допускающим во время работы выполнение пользовательских программ, представляет собой лазейку в системе безопасности.

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

LOGNAME

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

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

TZ

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

RCSINIT

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

Полезными в RCSINIT флагами могут быть -q, -V, -x и -z.

TMPDIR

Место для временных файлов. Если не задана, поочередно проверяются переменные TMP и TEMP и используется первая найденная, а и если они не заданы, то место для временных файлов по умолчанию зависит от операционной системы, но обычно, это /tmp .

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

СМ. ТАКЖЕ
co(1), emacs(1), ident(1), make(1), rcs(1), rcsclean(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1), setuid(2), 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.