ci

Check in RCS revisions (UNIX)

Syntax:

ci [options] file...

Options:

The ci utility does not follow the standard utility syntax conventions. Options and their arguments may not be separated by white space, and options may not be combined in single command line arguments (i.e. multiple options must be separated by spaces in the command line).

-d[date]

Use date for the checkin date and time. The date is specified in free format (see "Specifying date and time" in co). This option is useful for lying about the checkin date; it's also useful for option -k if no date is available. If you omit the date argument, ci uses the current date and time.

-f[rev]

Force a deposit. The new revision is deposited even if it's the same as the preceding one.

-i[rev]

Initial checkin; report an error if the RCS file already exists. This avoids race conditions in certain applications.

-I[rev]

Run interactively; prompt and question the user even if the standard input isn't a terminal.

-j[rev]

Just checkin and do not initialize; report an error if the RCS file does not already exist.

-k[rev]

Search the working file for keyword values to determine the file's revision number, creation date, state, and author, and assign these values to the deposited revision, rather than compute them locally.

-l[rev]

("el") Act as if -r were specified, except perform an additional co -l for the deposited revision. Thus, the deposited revision is immediately checked out again and locked. This is useful for saving a revision although you want to continue editing it after the checkin.

-mmsg

Use the string msg as the log message for all revisions checked in.

-M[rev]

Set modification date to that of the retrieved revision.

-n name

Assign the symbolic name name to the number of the checked-in revision. If name is already assigned to another number, ci prints an error message.

-Nname

Act as if -n were specified, except override a previous assignment of name.

-q[rev]

Be quiet; don't print diagnostic output.

-r[rev]

Assign the revision number rev to the checked-in revision, release the corresponding lock, and delete the working file. This is the default. The rev argument may be symbolic, numeric, or mixed.

-sstate

Set the state of the checked-in revision to state (default is Exp).

-t[file]

Write descriptive text from the contents of file into the RCS file, deleting the existing text. The filename may not begin with a dash (-). If you don't specify a file, ci prompts you to enter a description.

-T

Set the RCS file's modification time to the new revision's time if the former precedes the latter and there is a new revision; preserve the RCS file's modification time otherwise.

If you have locked a revision, ci usually updates the RCS file's modification time to the current time, because the lock is stored in the RCS file and removing the lock requires changing the RCS file. This can create an RCS file newer than the working file in one of two ways: first, ci -M can create a working file with a date before the current time; second, when reverting to the previous revision the RCS file can change while the working file remains unchanged. These two cases can cause excessive recompilation caused by a make dependency of the working file on the RCS file. The -T option inhibits this recompilation by lying about the RCS file's date. Use this option with care; it can suppress recompilation even when a checkin of one working file should affect another working file associated with the same RCS file. For example, suppose the RCS file's time is 01:00, the (changed) working file's time is 02:00, some other copy of the working file has a time of 03:00, and the current time is 04:00. Then ci -d -T sets the RCS file's time to 02:00 instead of the usual 04:00; this causes make to think (incorrectly) that the other copy is newer than the RCS file.

-u[rev]

Act as if -l were specified, except don't lock the deposited revision. This is useful for reading the working file immediately after checkin.

-V[n]

Report RCS version; or, if a number is supplied immediately after -V (no spaces), emulate RCS version n, where n may be 3, 4, or 5. This option can be useful when you're interchanging RCS files with other users who are running older versions of RCS (see also "Determining RCS version" in co).

-wlogin

Use login for the author field of the deposited revision. This option is useful for lying about the author; it's also useful for the -k option if no author is available.

-xsuffixes

Specifies the suffixes for RCS files. A nonempty suffix matches any pathname ending in the suffix. An empty suffix matches any pathname of the form RCS/path or path1/RCS/path2. The -x option can specify a list of suffixes separated by /. 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 an 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 ,v/.

-zzone

Specifies the date output format in keyword substitution, and specifies the default time zone for date in the -ddate option. The zone should be empty, a numeric UTC offset in the form

• [+|-]hh:mm

or the special string LT for local time. The default is an empty zone, which uses the traditional RCS format of UTC without any time zone indication and with slashes separating the parts of the date; otherwise, times are output in ISO 8601 format with time zone indication.

The -z option does not affect dates stored in RCS files, which are always UTC.

file

The pathname of an RCS file and/or a working file.

Description:

The ci utility stores new revisions into RCS files. Each filename ending in ,v is taken to be an RCS file. All others are assumed to be working files containing new revisions. The ci utility deposits the contents of each working file into the corresponding RCS file. If only a working file is given, ci tries to find the corresponding RCS file in an RCS subdirectory and then in the working file's directory.

If the RCS file doesn't exist, ci 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 requests descriptive text (see "Descriptive text," below).

For each revision, ci prints the RCS file, the working file, and the number of both the deposited and the preceding revision.

File naming

You can specify pairs of RCS files and working files in three ways (see also the Example section of co):

1. Both the RCS file and the working file are given. The RCS filename is of the form path1/workfile,v and the working filename is of the form path2/workfile where path1/ and path2/ are possibly different or empty paths and workfile is a filename.
2. Only the RCS file is given. Then the working file is created in the current directory and its name is derived from the name of the RCS file by removing path1/ and the ,v suffix.
3. Only the working file is given. Then ci looks for an RCS file of 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 (above), then ci looks for the RCS file first in the directory ./RCS and then in the current directory.

For ci to work...

For ci 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 tip revision on that branch must be locked by the caller. Otherwise, only a new branch can be created. This restriction isn't enforced for the owner of the file if non-strict locking is used (see rcs). A lock held by someone else may be broken with the rcs command.

Forcing a deposit

Normally, ci checks whether the revision to be deposited differs from the preceding one. If they're the same, ci reverts to the preceding revision instead of creating a new revision. To force a deposit, you use the -f option. The ci utility will deposit a revision that's the same as the preceding revision only if -f is specified.

Log messages

For each revision deposited, ci prompts you for a log message. The log message you enter should summarize the change and must be terminated by EOF or by a line containing only a single dot (.). If several files are checked in, ci asks whether to reuse the previous log message. If the standard input isn't a terminal, ci suppresses the prompt and uses the same log message for all files. You can also use the -m option to specify the same log message for all revisions checked in.

Descriptive text

The -t option, in both its forms, is effective only during an initial checkin; it's silently ignored otherwise. During the initial checkin, if -t isn't given, ci obtains the text from standard input, terminated by EOF or by a line containing only a dot (.). 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.

Keywords

The -k option generates a default checkin message noting the login of the caller and the actual checkin date. This option is useful for software distribution. A revision that is sent to several sites should be checked in with the -k option at these sites to preserve the original number, date, author, and state. The extracted keyword values and the default log message may be overridden with the options -d, -m, -s, -w, and any option that carries a revision number. For more information on keywords, see the co utility.

Options using rev

You can specify the number of the deposited revisions by any of the options -f, -I, -k, -l, -q, -r, or -u. The following rules apply using rev:

* Note that on the trunk, revisions can be appended to the end, but not inserted.

File modes

An RCS file created by ci inherits the read and execute permissions from the working file. If the RCS file already exists, ci preserves the RCS file's read and execute permissions. The ci utility always turns off all write permissions of RCS files.

Files:

Several temporary files may be created. A semaphore file is created in the directory containing the RCS file. The effective user and group must be able to read the RCS file and to search and write the directory containing the RCS file. Normally, the real user and group must be able to read the working file and to search and write the directory containing the working file. The effective user and group are the same as the real user and group unless your RCS executables have setuid or setgid privileges. These privileges yield extra security if RCS files are protected so that only the effective user and group can write RCS directories. Further protection can be achieved by granting access only to the effective user and group.

The ci utility never changes an RCS file or a working file; instead, it unlinks the file and creates a new one. This strategy breaks hard links to such files, but doesn't affect symbolic links.

Exit status:

0

Successful completion.

>0

An error occurred.

The exit status is zero only if all operations were successful.

Contributing author:

GNU

See also:

co, ident, rcs, rcsdiff, rcsmerge, rlog

Walter F. Tichy, "RCS -- A System for Version Control," Software -- Practice & Experience 15, 7, July 1985.

Don Bolinger & Tan Bronson, Applying RCS & SCCS, O'Reilly & Associates, 1995.