ci [ options ] file ...
Ci(1) stores new revisions into Revision Control System (RCS) files. Each path name matching an RCS suffix is taken to be an RCS file. All others are assumed to be working files containing new revisions. Ci(1) deposits the contents of each working file into the corresponding RCS file. If only a working file is given, ci(1) tries to find the corresponding RCS file in an RCS subdirectory and then in the directory of the working file. (For more details, see FILE NAMING.)
(A detailed discussion of the way ci(1)behaves follows OPTIONS.)
The -r option has an unusual meaning in ci(1). In other RCS commands, -r merely specifies a revision number. In ci(1), however, it also releases a lock and removes the working file. See -u for information about how -r interacts with other options.
The -t option, in both its forms, has effect only during an initial check in; otherwise, it is silently ignored. During the initial check in, if -t is not given, ci(1) obtains the text from standard input, terminated by end-of-file or by a line containing .(dot) by itself. The user is prompted for the text if interaction is possible. (See -I.) For backward compatibility with older versions of RCS, a bare -t option is ignored.
The -l, -r, and -u options are mutually exclusive and silently override each other. For example, ci -u -r is equivalent to ci -R because -r overrides -u.
For ci(1) to work, the caller's login must be on the access list unless the access list is empty, or the caller is the superuser or the owner of the file. To append a new revision to an existing branch, the caller must first lock the tip revision on that branch. Otherwise, the caller can only create a new branch. This restriction is not enforced for the owner of the file if nonstrict locking is used (see rcs(1)). A lock held by someone else may be broken with the rcs(1) command.
Ci(1) checks to determine whether the revision to be deposited differs from the preceding version (unless the -f option is given). If the revision does not differ, ci(1) reverts to the preceding version instead of creating a new revision. To revert, ci(1) removes the working file and any lock; this is modified by the options -l and -u. ci -l keeps any lock, and ci -u removes any lock. Then, they both generate a new working file, much as if co -l or co -u had been applied to the preceding revision. When reverting, any -n and -s options apply to the preceding revision.
For each revision deposited, ci(1) prompts for a log message. The log message should summarize the change and must be terminated by end-of-file or by a line containing . (dot) by itself. If several files are checked in, ci(1) asks whether to reuse the previous log message. If the standard input is not a terminal, ci(1) suppresses the prompt and uses the same log message for all files. (See -m.)
If the RCS file does not exist, ci(1) creates it and deposits the contents of the working file as the initial revision (default number: 1.1). The access list is initialized to empty. Instead of the log message, ci(1) requests descriptive text. (See -t.)
The number rev of the deposited revision can be given by any of the following options:
-f
-I
-k
-l
-M
-q
-r
-u
rev may be symbolic, numeric, or mixed. If rev is
$, ci(1) determines the revision number from
keyword values in the working file.
If rev is a revision number, it must be higher than the latest one on the branch to which rev belongs, or 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 tip revision number of that branch. If rev indicates a nonexisting branch, that branch is created with the initial revision numbered rev.1.
If rev is omitted, ci(1) 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 non-tip revision, a new branch is started at that revision by incrementing the highest branch number at that revision. The default for the initial branch and level numbers is 1.
If rev is omitted, and the caller has no lock but owns the file, and locking is not set to strict, the revision is appended to the default branch (normally the trunk; see the -b option of rcs(1)).
An exception is that, on the trunk, revisions can be appended to the end but not inserted.
If the RCS file is specified without a path in 1) and 2), ci(1) looks for the RCS file, first in the directory ./RCS, and then in the current directory.
Ci(1) reports an error if an attempt to open an RCS file fails for an unusual reason, even if the RCS file's path name is just one of several possibilities. For example, to suppress use of RCS commands in a directory d, create a regular file named d/RCS so that casual attempts to use RCS commands in d fail because d/RCS is not a directory.
$ 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
If, however, the empty suffix is an RCS suffix and the current directory contains a subdirectory RCS with an RCS file io.c, each of the following commands checks in a new revision:
$ ci io.c
$ ci RCS/io.c
$ ci io.c RCS/io.c
$ ci RCS/io.c io.c
An RCS file created by ci(1) inherits read-and-execute permissions from the working file. If the RCS file already exists, ci(1) preserves its read-and-execute permissions. Ci(1) always turns off all write permissions of RCS files.
Several temporary files can be created in the directory containing the working file, and can also be created in the temporary directory (see TMPDIR under ENVIRONMENT). A semaphore file or files are created in the directory containing the RCS file. 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 file name. With an empty suffix, the semaphore names end with _, so working filenames should not end in _.
Ci(1) never changes an RCS or working file. Usually, ci(1) unlinks the file and creates a new one. Instead of breaking a chain of one or more symbolic links to an RCS file, it unlinks the destination file. As a result, ci(1) breaks any hard or symbolic links to any working file it changes, and hard links to RCS files are ineffective. Symbolic links to RCS files, however, are preserved.
The effective user must be able to search and write the directory containing the RCS file. Usually, the real user must be able to read the RCS and working files, and search and write the directory containing the working file. Some older hosts cannot switch easily between real and effective users, however. On these older hosts, the effective user is used for all accesses. The effective user is the same as the real user unless your copies of ci(1) and co(1) have setuid privileges. As described in the next section, these privileges provide 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, on hosts that allow a user to belong to several groups, you can make a group's RCS directories writable to that group only. Although this is usually sufficient for informal projects, this approach allows any group member to change the group's RCS files, or even remove them entirely. To prevent these types of problems, 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.
The ci(1) command makes use of the following environment variables:
For each revision, ci(1) prints the RCS file, the working file, and the number of both the deposited and the preceding revision. The exit status is zero only if all operations were successful.
co(1)
ident(1)
make(1)
rcs(1)
rcsdiff(1)
rcsmerge(1)
rlog(1)
rcsfile(5)
rcsintro(5)
Walter F. Tichy, RCS--A System for Version Control, Software--Practice & Experience 15, 7 (July 1985), 637-654.