ci(1) CLIX ci(1)
NAME
ci - Checks in RCS revisions
SYNOPSIS
ci [flag ... ] file ...
FLAGS
-r[rev] Assigns the revision number rev to the checked-in revision,
releases the corresponding lock, and deletes the working
file. This flag is the default. The rev may be symbolic,
numeric, or mixed. This flag cannot be used with the -l
and -u flags.
If rev is a revision number, it must be higher than the
latest one on the branch to which rev belongs or it must
start a new branch.
If rev is a branch rather than a revision number, the new
revision is appended to that branch. The level number is
obtained by incrementing the branch's tip revision number.
If rev indicates a nonexisting branch, the branch is
created with the initial revision numbered rev.1.
If rev is omitted, ci tries to derive the new revision
number from the caller's last lock. If the caller has
locked the tip revision of a branch, the new revision is
appended to that branch. The new revision number is
obtained by incrementing the tip revision number. If the
caller locked a nontip revision, a new branch is started at
that revision by incrementing the highest branch number at
that revision. The default initial branch and level
numbers are both 1.
If rev is omitted and the caller has no lock but is the
owner of the file and locking is not set to strict, the
revision is appended to the default branch (normally the
trunk; see rcs(1) with the -b flag).
However, on the trunk, revisions can be appended, but not
inserted.
-f[rev] Forces a deposit. The new revision is deposited even if it
does not differ from the preceding one.
-I[rev] (Interactive mode.) Prompts the user even if the standard
input is not a terminal.
-k[rev] Searches the working file for keyword values to determine
2/94 - Intergraph Corporation 1
ci(1) CLIX ci(1)
its revision number, creation date, state, and author (see
co(1)), and assigns these values to the deposited revision,
rather than computing them locally. It also generates a
default login message noting the login of the caller and
the actual check-in date. This flag is useful for software
distribution. A revision sent to several sites should be
checked in at these sites with the -k flag to preserve the
original number, date, author, and state. The extracted
keyword values and the default log message may be
overridden with the -r, -d, -s, -w, and -m flags. If date
is empty, the working file's time of last modification is
used.
-l[rev] Works like the -r flag, except it performs an additional co
-l command for the deposited revision. Thus, the deposited
revision is immediately checked out again and locked. This
is useful for saving a revision although one wants to
continue editing it after the check-in. This flag cannot be
used with the -r and -u flags.
-M [rev] Sets the modification time on any new working file to be
the date of the retrieved revision. For example, ci -d -M
-u f does not alter the modification time of s, even if the
contents of f change due to keyword substitution. Use this
flag with care--it can confuse the make command.
-u[rev] Works like the -l flag, except that the deposited revision
is not locked. This is useful to process (compile) the
revision immediately after check-in. This flag cannot be
used with the -r and -l flags.
-q[rev] Specifies quiet mode. Diagnostic output is not displayed.
A revision that is not different from the preceding one is
not deposited unless the -f flag is given.
-ddate Uses date for the check-in date and time. The date may be
specified in free format as explained in co(1). Useful for
lying about the check-in date and for the -k flag if no
date is available.
-mmsg Uses the string msg as the log message for all revisions
checked in.
-nname Assigns the symbolic name name to the number of the
checked-in revision. The ci command displays an error
message if name is assigned to another number.
-Nname Same as the -n flag, except that it overrides a previous
assignment of name.
-sstate Sets the state of the checked-in revision to the identifier
2 Intergraph Corporation - 2/94
ci(1) CLIX ci(1)
state. The default is Exp.
-t[txtfile] Writes descriptive text into the RCS file. Any existing
text is deleted. If txtfile is omitted, ci prompts the
user for text supplied from stdin, terminated with a line
containing a single ``.'' or the <Ctrl-D> sequence.
Otherwise, the descriptive text is copied from the file
txtfile. During initialization, descriptive text is
requested even if the -t flag is not given. The prompt is
suppressed if stdin is not a terminal.
-t- string Writes descriptive text from the string into the RCS file,
deleting the existing text.
The -t flag, in both of its forms, has effect only during
an initial check-in; it is ignored otherwise.
During the initial check-in, if the -t flag is not used, ci
obtains the text from stdin, terminated by an end-of-file
character or by a line containing a period (.) by itself.
The user is prompted for the text if interaction is
possible (see the -I flag description).
For backward compatibility with older versions of RCS, a -t
flag with no argument is ignored.
-wlogin Uses login for the author field of the deposited revision.
Useful for lying about the author and for the -k flag if no
author is available.
-Vn Emulates RCS version n. See co(1) for more information.
-x suffixes Specifies the suffixes for RCS files. A non-empty suffix
matches any pathname ending in the suffix. An empty suffix
matches any pathname of the form RCS/file or path/RCS/file.
The -x flag can specify a list of suffixes separated by a
slash (/). For example, -x,v/ specifies two suffixes: ,v
and the empty suffix. If two or more suffixes are
specified, they are tried in order when looking for a RCS
file; the first one that works is used for that file. If
no RCS file is found but an RCS file can be created, the
suffixes are tried in order to determine the new RCS file's
name. The default for suffixes is installation-dependent;
normally it is ,v/ for hosts like UNIX that permit commas
in file names, and is empty (the empty suffix) for other
hosts.
DESCRIPTION
The ci command stores new revisions in Revision Control System (RCS)
files. If no flags are specified, ci uses the -r flag by default. Each
2/94 - Intergraph Corporation 3
ci(1) CLIX ci(1)
filename ending in ``,v'' is interpreted to be an RCS file; all others are
assumed to be working files containing new revisions. The ci command
deposits the contents of each working file in the corresponding RCS file.
If only a working file is given, ci tries to find the corresponding RCS
file in the ./RCS directory and then in the current directory. For more
details, see the File Naming in this text.
For ci to work, the caller's login must be on the access list, except if
the access list is empty or the caller is the superuser or owner of the
file. To append a new revision to an existing branch, the tip revision on
that branch must be locked by the caller. Otherwise, only a new branch
can be created. This restriction is not enforced for the owner of the
file unless locking is set to strict (see rcs(1)). A lock held by another
user may be broken with the rcs command.
Normally, ci checks whether the revision to be deposited is different from
the preceding one. If it is not, ci either aborts the deposit (if -q is
given) or asks whether to abort (if -q is omitted). A deposit can be
forced with the -f flag.
For each revision deposited, ci prompts for a log message. The log
message should summarize the change and must be terminated with a line
containing a single ``.'' or the <Ctrl-D> sequence. If several files are
checked in, ci asks whether to reuse the previous log message. If the
stdin is not a terminal, ci suppresses the prompt and uses the same log
message for all files. See also the -m flag.
The number of the deposited revision can be given by any of these flags:
-r, -f, -k, -l, -u, or -q.
If the RCS file does not exist, ci creates it and deposits the contents of
the working file as the initial revision (with a default number of 1.1).
The access list is initialized to empty. Instead of requesting the log
message, ci requests descriptive text (see -t flag).
File Naming
Pairs of RCS files and working files may be specified in three ways (see
also the example section of co(1)).
1. Both the RCS file and the working file are given. The RCS filename
has the form path1/workfileX and the working filename has the form
path2/workfile, where path1/ and path2/ are possibly different or
empty paths, workfile is a filename, and X is an RCS suffix. If X is
an empty suffix, path1/ must be RCS/ or must end in /RCS/.
2. Only the RCS file is given. Then, the working file is assumed to be
in the current directory and its name is derived from the name of the
RCS file by removing path1/ and the suffix ``,v''.
3. Only the working file is given. Then ci looks for an RCS file with
4 Intergraph Corporation - 2/94
ci(1) CLIX ci(1)
the form path2/RCS/workfile,v or path2/workfile,v (in this order).
If the RCS file is specified without a path in 1) and 2), ci looks for the
RCS file first in the directory ./RCS and then in the current directory.
File Modes
An RCS file created by ci inherits the read and execute permissions from
the working file. If the RCS file exists, ci preserves its read and
execute permissions. The ci command always turns off all write
permissions of RCS files.
Mapping File Comment Leaders
When the user initially checks in a file, RCS uses the file's extension to
determine a comment leader. The comment leader is a sequence of one or
more characters placed at the beginning of a line in the file to denote
that the text following it is a comment. Comments are ignored during
compliation.
When the user checks in a file for the first time, RCS looks at its
extension to try to determine the source language, and chooses an
appropriate comment leader. This leader is stored in the ,v file, and is
placed before any information that RCS inserts into the source file.
Below is a table describing the mapping between extensions and languages,
and the comment leader used for each language:
Extension Language Assumed Leader
--------- ---------------- ------
.a Ada --
.ada Ada --
.asm assembler (MS-DOS) ;;
.bat batch (MS-DOS) ::
.c C *
.c++ C++ //
.cc C++ //
.cpp C++ //
.cxx C++ //
.cl Common Lisp ;;;
.cmd command (OS/2) ::
.cmf CM Fortran c
.cs C* *
.el Emacs Lisp ;
.f Fortran c
.for Fortran c
.h C-header *
.hpp C++ header //
.hxx C++ header //
.l lex *
.lisp Lucid Lisp ;;;
.lsp Microsoft Lisp ;;
2/94 - Intergraph Corporation 5
ci(1) CLIX ci(1)
.mac macro ;;
.me me-macros (t/nroff) .\"
.ml mocklisp ;
.mm mm-macros (t/nroff) .\"
.ms ms-macros (t/nroff) .\"
.p Pascal *
.pas Pascal *
.pl Prolog %
.tex TeX %
.y yacc *
A default comment leader of # is used when there is no suffix, or when the
suffix is not found in the list above.
This mapping is not foolproof, however. The .l extension may result in a
conflict between lex and franzlisp files; Perl files ending in .pl are
assumed to be Prolog source. If there are no keywords like $Log$ in the
source, this should not be a problem; but if so, RCS may make an
erroneous assumption and use the wrong comment character when adding
information to the file. There are two work-arounds for this problem.
The first is to change the extension of the file, and the second is to use
rcs to change the comment leader for the file.
If the file contains one of the types of source in the table, it may be
useful adopt the extension that RCS assumes for that language and check
the file in fresh. This will avoid the problem if the file is checked
into RCS again, and may even help to improve the organization of the
sources.
If for some reason it is impossible or unreasonable to rename the file
(perhaps the compiler expects the current extension or many other files
include this source), the user can simply change the comment leader using
the rcs -c command. For example, to set the comment leader for a Perl
script file named script.pl to "# ", go to the directory where script.pl,v
resides (or directly above it if using an RCS subdirectory), and enter the
following command:
rcs -c"# " script.pl
Once the comment leader has been changed, the new leader will be used for
all comments generated by RCS when the user later checks out the source.
Files
Several temporary files may be created in the directory containing the
working file, and also in the temporary directory (see the TMPDIR
description in ``Environment Variables'').
Semaphore files are created in the directory containing the RSC file.
6 Intergraph Corporation - 2/94
ci(1) CLIX ci(1)
With a nonempty suffix, the semaphore names begin with the first character
of the suffix; therefore, do not specify a suffix whose first character
could be that of a working filename. With an empty suffix, the semaphore
names end with an underscore (_), so working filenames should not end in
_.
The ci commane never changes an RCS or working file. Normally, ci unlinks
the file and creates a new one; but instead of breaking a chain of one or
more symbolic links to an RCS file, it unlinks the destination file
instead. Therefore, ci breaks any hard or symbolic links to any working
file it changes; and hard links to RCS files are ineffective, but symbolic
links to RCS files are preserved.
The effective user must be able to search and write the directory
containing the RCS file. Normally, the real user must be able to read the
RCS and working files and to search and write the directory containing the
working file; however, some older hosts cannot easily switch between real
and effective users, so on these hosts the effective user is used for all
accesses. The effective user is the same as the real user unless ci and
co have setuid privileges. As described in ``Setuid Use,'' these
privileges yield extra security if the effective user owns all RCS files
and directories, and if only the effective user can write RCS directories.
Users can control access to RCS files by setting the permissions of the
directory containing the files; only users with write access to the
directory can use RCS commands to change its RCS files. For example, in
hosts that allow a user to belong to several groups, make a group's RCS
directories writable to that group only. This approach suffices for
informal projects, but it means that any group member can arbitrarily
change the group's RCS files, and can even remove them entirely. Hence
more formal projects sometimes distinguish between an RCS administrator,
who can change the RCS files at will, and other project members, who can
check in new revisions but cannot otherwise change the RCS files.
Setuid Use
To prevent anybody but their RCS administrator from deleting revisions, a
set of users can employ setuid privileges as follows.
1. Check that the host supports RCS setuid use. It is best if the
seteuid() system call works as described in Posix 1003.1a Draft 5,
because RCS can switch back and forth easily between real and
effective users, even if the real user is root. If not, the second
best is if the setuid() system call supports saved setuid (the
{_POSIX_SAVED_IDS} behavior of Posix 1003.1-1990); this fails only if
the real user is root. If RCS detects any failure in setuid, it quits
immediately.
2. Choose a user A to serve as RCS administrator for the set of users.
Only A will be able to invoke the rcs command on the users' RCS files.
User A should not be root or any other privileged user.
2/94 - Intergraph Corporation 7
ci(1) CLIX ci(1)
3. Choose a path name B that will be a directory of files to be executed
by the users.
4. Have user A set up path name B to contain copies of ci and co that are
setuid to user A by copying the commands from their standard
installation directory D as follows:
$ mkdir B
$ cp D/c[io] B
$ chmod go-w,u+s B/c[io]
5. Have each user prepend path name B to their path as follows:
PATH=B:$PATH; export PATH # ordinary shell
set path=(B $path) # C shell
6. Have user A create each RCS directory R with write access only to A as
follows:
$ mkdir R
$ chmod go-w R
7. To let only certain users read the RCS files, put the users into a
group G, and have user A further protect the RCS directory as follows:
$ chgrp G R
$ chmod g-w,o-rwx R
8. Have user A copy old RCS files (if any) into the RCS directory R, to
ensure that user A owns them.
9. Create an RCS file access list. This list limits who can check in and
lock revisions for a file. The default access list is empty, which
grants check-in access to anyone who can read the RCS file. To limit
check-in access, have user A use the rcs -a command on the file. (See
rcs(1) for more information.) In particular, rcs -e -a A limits
access to just user A.
10. Have user A initialize any new RCS files with rcs -i before initial
check-in, adding the -a flag to limit check-in access.
11. Give setuid privileges only to ci, co, and rcsclean; do not give them
to rcs or to any other command.
Note: Do not use other setuid commands to invoke RCS commands.
Environment Variables
8 Intergraph Corporation - 2/94
ci(1) CLIX ci(1)
The following environment variables can be useful with RCS:
RCSINIT Specifies options prepended to the argument list, separated by
spaces. A backslash escapes spaces within an option. The
RCSINIT options are prepended to the argument lists of most RCS
commands. Useful RCSINIT options include -q, -V, and -x.
TMPDIR Names the temporary directory. If not set, the environment
variables TMP and TEMP are inspected instead and the first value
found is taken; if none of them are set, a host-dependent
default is used, typically /tmp.
EXAMPLES
This example checks in the file draft.text, giving it a revision number
one greater than the latest revision, and then checks out the file again,
setting it to ``unlocked.''
rci -u draft.text
FILES
*,RCSnewxxxxxx Temporary file for the new revision.
*,RCScixxxxxx Temporary difference file.
/tmp/,RCSt3xxxxxx Temporary file.
NOTES
Use the -M flag with care, as it can confuse the make command.
The caller of the command must have read/write permission for the
directories containing the RCS file and the working file, and read
permission for the RCS file itself. A number of temporary files are
created. A semaphore file is created in the directory containing the RCS
file. The ci command always creates a new RCS file and unlinks the old
one. This strategy makes links to RCS files useless.
A default comment leader of # is used when there is no suffix, or when the
suffix is not found in the list or recognized suffixes.
CAUTIONS
File comment mapping is not foolproof. The .l extension may result in a
conflict between lex and franzlisp files; Perl files ending in .pl are
assumed to be Prolog source. If there are no keywords like $Log$ in the
source, this should not be a problem; but if so, RCS may make an
erroneous assumption and use the wrong comment character when adding
information to the file. There are two work-arounds for this problem.
2/94 - Intergraph Corporation 9
ci(1) CLIX ci(1)
The first is to change the extension of the file, and the second is to use
rcs to change the comment leader for the file.
DIAGNOSTICS
For each revision, ci displays the RCS file, the working file, and the
number of both the deposited and the preceding revisions.
EXIT VALUES
The exit value always refers to the last file checked in and is 0 if the
operation was successful, or 1 otherwise.
RELATED INFORMATION
Commands: co(1), ident(1), rcs(1), rcsclean(1), rcsdiff(1), rcsmerge(1),
rlog(1), sccstorcs(1)
Files: rcsfile(4)
Walter F. Tichy, ``Design, Implementation, and Evaluation of a Revision
Control System,'' in Proceedings of the 6th International Conference on
Software Engineering, IEEE, Tokyo, Sept. 1982
Walter F. Tichy, ``RCS--A System for Version Control,'' Software--
Practice & Experience, 15, 7 (July 1985), pp. 637-654.
10 Intergraph Corporation - 2/94