co(1) CLIX co(1)
NAME
co - Checks out RCS revisions
SYNOPSIS
co [flag ... ] file ...
FLAGS
-r[rev] Retrieves the latest revision which has a number less than or
equal to rev. If rev indicates a branch rather than a
revision, the latest revision on that branch is retrieved.
If rev is omitted, the latest revision on the default branch
(see rcs(1) with the -b flag) is retrieved. If rev is $, co
determines the revision number from keyword values in the
working file. Otherwise, a rev is composed of one or more
numeric or symbolic fields separated by periods (.). The
numeric equivalent of a symbolic field is specified with the
-n flag of the commands ci and rcs.
-l[rev] Same as the -r flag except that it also locks the retrieved
revision for the caller. See the -r flag to see how revision
number rev is handled.
-u[rev] Same as the -r flag except that it unlocks the retrieved
revision (if it was locked by the caller). If rev is
omitted, -u retrieves the latest revision locked by the
caller. If no such lock exists, it retrieves the latest
revision on the default branch.
-f[rev] Forces the working file to be overwritten. Useful when used
with the -q flag. (See also the section on File Modes in
this text.)
-kkv Generates keyword strings using the default form (for
example, $Revision: 5.7 $ for the Revision keyword. A
locker's name is inserted in the value of the Header, Id, and
Locker keyword strings only as a file is being locked (that
is, by the commands ci -l and co -l). This is the default.
-kkvl Similar to the -kkv flag, except that a locker's name is
always inserted if the given revision is currently locked.
-kk Generates only keyword names in keyword strings; the values
of the keywords are omitted. (See the Keyword Sustitution
section for more information.) For example, for the Revision
keyword, co generates the string $Revision$ instead of
$Revision: 5.7 $. This flag is useful to ignore differences
due to keyword substitution when comparing different
revisions of a file.
2/94 - Intergraph Corporation 1
co(1) CLIX co(1)
-ko Generates the old keyword string that was present in the
working file just before it was checked in. For example, for
the Revision keyword, co generates the string $Revision: 1.1
$ instead of $Revision: 5.7 $, if that is how the string
appeared when the file was checked in. This can be useful
for binary file formats that cannot tolerate any changes to
substrings that happen to take the form of keyword strings.
-kv Generates only keyword values for keyword strings. For
example, for the Revision keyword, co generates the string
5.7 instead of $Revision: 5.7 $. This can help generate
files in programming languages where it is hard to strip
keyword delimiters like $Revision: $ from a string. However,
further keyword substitution cannot be performed once the
keyword names are removed, so this flag should be used with
care. Because of this danger of losing keywords, this flag
cannot be combined with the -l flag, and the owner write
permission of the working file is turned off; to edit the
file later, check it out again without the -kv flag.
-p[rev] Displays the retrieved revision on stdout rather than storing
it in the working file. This flag is useful when co is part
of a pipe.
-q[rev] Specifies quiet mode. Diagnostics are not displayed.
-I[rev] (Interactive mode.) The user is prompted even if stdin is
not a terminal.
-ddate Retrieves the latest revision on the selected branch which
has a checkin date/time is less than or equal to date. The
date and time may be given in free format. The time zone LT
stands for local time; other common time zones are
understood. For example, the following dates are equivalent
if local time is January 11, 1990, 8pm Pacific Standard Time,
eight hours west of Coordinated Universal Time (UTC):
8:00 pm lt
4:00 AM, Jan. 12, 1990 note: default is UTC
1990/01/12 04:00:00 RCS date format
Thu Jan 11 20:00:00 1990 LT output of ctime + LT
Thu Jan 11 20:00:00 PST 1990 output of date
Fri Jan 12 04:00:00 GMT 1990
Thu, 11 Jan 1990 20:00:00 -0800
Fri-JST, 1990, 1pm Jan 12
12-January-1990, 04:00-WET
Most fields in the date and time allow the use of a default.
The default time zone is UTC. The co command determines the
defaults in the order of year, month, day, hour, minute, and
2 Intergraph Corporation - 2/94
co(1) CLIX co(1)
second (most to least significant). At least one of these
fields must be provided. For omitted fields with higher
significance than the highest provided field, the current
values are assumed. For all other omitted fields, the lowest
possible values are assumed. For example, the date 20, 10:30
defaults to 10:30:00 UTC of the 20th of the current month and
year. The date/time must be quoted if it contains spaces.
-M[rev] Sets the modification time on the new working file to be the
date of the retrieved revision. Use this flag with care, as
it can confuse the make command.
-sstate Retrieves the latest revision on the selected branch which
has a state set to state.
-w[login] Retrieves the latest revision on the selected branch that was
checked in by the user with login name login. If the
argument login is omitted, the caller's login is assumed.
-jjoinlist Generates a new revision that is the join of the revisions on
joinlist. This flag is obsolete because of the rcsmerge
command, but is retained for backwards campatibility.
The joinlist is a comma-separated list of pairs of the form
rev2:rev3, where rev2 and rev3 are symbolic or numeric
revision numbers. For the initial such pair, rev1 denotes
the revision selected by the above flags. For all other
pairs, rev1 denotes the revision generated by the previous
pair. (Thus, the output of one join becomes the input to the
next.)
For each pair, co joins revisions rev1 and rev3 with respect
to rev2. This means that all changes that transform rev2
into rev1 are applied to a copy of rev3. This is useful if
rev1 and rev3 are the ends of two branches that have rev2 as
a common ancestor. If rev1<rev2<rev3 on the same branch,
joining generates a new revision that is like rev3, but with
all changes that lead from rev1 to rev2 undone. If changes
from rev2 to rev1 overlap changes from rev2 to rev3, co
displays a warning and includes the overlapping sections,
delimited by the lines <<<<<<< rev1, =======, and >>>>>>>
rev3.
For the initial pair, rev2 may be omitted. The default is
the common ancestor. If any arguments indicate branches, the
latest revisions on those branches are assumed. The -l and
-u flags lock or unlock rev1, respectively.
-Vn Emulates RCS version n, where n may be 3, 4, or 5. This may
be useful when interchanging RCS files with others who are
running older versions of RCS. To see which version of RCS
2/94 - Intergraph Corporation 3
co(1) CLIX co(1)
others are running, have them use the rlog command on an RCS
file; if none of the first few lines of output contain the
string branch: it is version 3; if the dates' years have
just two digits, it is version 4; otherwise, it is version 5.
An RCS file generated while emulating version 3 will lose its
default branch. An RCS revision generated while emulating
version 4 or earlier will have a timestamp that is off by up
to 13 hours. A revision extracted while emulating version 4
or earlier will contain dates of the form yy/mm/dd instead of
yyyy/mm/dd and may also contain different white space in the
substitution for $Log$.
-x suffixes Uses suffixes to characterize 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 co command retrieves a revision from each Revision Control System
(RCS) file and stores it into the corresponding working file. Each
filename ending in ``,v'' is assumed to be an RCS file; all other files
are assumed to be working files. If only a working file is given, co
tries to find the corresponding RCS file in the directory ./RCS and then
in the current directory. For more details, see the File Naming section
in this text.
Revisions of an RCS file may be checked out as locked or unlocked.
Locking a revision prevents overlapping updates. A revision checked out
for reading or processing (compiling) need not be locked. A revision
checked out for editing and later checkin must normally be locked. The co
command with locking fails if the revision to be checked out is currently
locked by another user. (A lock may be broken with the rcs command.) The
co command with locking also requires the caller to be on the access list
of the RCS file unless the caller is the file owner or the superuser, or
the access list is empty. The co command without locking is not subject
to access list restrictions, and is not affected by locks.
A revision is selected by flags for revision or branch number, check-in
date/time, author, or state. When the selection flags are applied in
combination, co retrieves the latest revision that satisfies all of them.
If no selection flag is specified, co retrieves the latest revision on the
4 Intergraph Corporation - 2/94
co(1) CLIX co(1)
default branch. (Normally the trunk, see rcs(1) with the -b flag.) A
revision or branch number may be attached to the -f, -I, -l, -M, -p, -q,
-r, or -u flags. The -d (date), -s (state), and -w (author) flags
retrieve from a single branch, the selected branch that is either
specified by the -f, -I, -l, -M, -p, -q, -r, -u flags, or the default
branch.
A co command applied to an RCS file with no revisions creates a zero-
length working file. The co command always performs keyword substitution.
Keyword Substitution
Strings with the form $keyword$ and $keyword: ... $ embedded in the text
are replaced with strings with the form $keyword: value $, where keyword
and value are pairs listed below. Keywords may be embedded in literal
strings or comments to identify a revision.
Initially, the user enters strings with the form $keyword$. On checkout,
co replaces these strings with strings with the form $keyword: value $.
If a revision containing strings with the latter form is checked back in,
the value fields will be replaced during the next checkout. Thus, the
keyword values are automatically updated at checkout. This automatic
substitution can be modified with the -k flags.
Keywords and their corresponding values are as follows:
$Author$ The login name of the user who checked in the revision.
$Date$ The date and time the revision was checked in.
$Header$ A standard header containing the full pathname of the RCS
file, the revision number, the date, the author, the state,
and the locker (if locked).
$Id$ Same as $Header$ except that the RCS filename has no path.
$Locker$ The login name of the user who locked the revision (empty if
not locked).
$Log$ The log message supplied during checkin, preceded by a
header containing the RCS filename, the revision number, the
author, and the date. Existing log messages are not
replaced. Instead, the new log message is inserted after
$Log: ... $. This is useful for accumulating a complete
change log in a source file.
$RCSfile$ The name of the RCS file without path.
$Revision$ The revision number assigned to the revision.
$Source$ The full pathname of the RCS file.
2/94 - Intergraph Corporation 5
co(1) CLIX co(1)
$State$ The state assigned to the revision with rcs -s or ci -s.
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
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
The working file inherits the read and execute permissions from the RCS
file. In addition, the owner write permission is turned on, unless -kv is
set or the file is checked out unlocked, and locking is set to strict (see
rcs(1)).
If a file with the name of the working file exists and has write
permission, co aborts the checkout if -q is given or asks whether to abort
if not. If the existing working file is not writable or -f is given, it
is deleted without confirmation.
Environment Variables
The following environment variable 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.
EXAMPLES
1. Suppose the current directory contains a subdirectory RCS with an RCS
file io.c,v. Then, all of the following commands retrieve the latest
revision from RCS/io.c,v and store it in io.c.
co io.c; co RCS/io.c,v;
6 Intergraph Corporation - 2/94
co(1) CLIX co(1)
co io.c,v; co io.c RCS/io.c,v;
co io.c io.c,v; co RCS/io.c,v io.c;
co io.c,v io.c;
2. This example checks out an unlocks the retrieved revision of every
file in the RCS directory.
co -u RCS/*,v
FILES
*,RCSnewxxxxxx Temporary file for the new revision.
/tmp/,RCSjxxxxxx Temporary file.
,RCSxxxxxx, Semaphore file.
NOTES
Use the -M flag with care, as it can confuse the make command.
The user of the command must have write permission in the working
directory, read permission for the RCS file, and either read permission
(for reading) or read/write permission (for locking) in the directory that
contains the RCS file.
A number of temporary files are created. A semaphore file is created in
the directory of the RCS file to prevent simultaneous update.
The expansion of keywords cannot be suppressed except by writing them
differently. In nroff and troff, this is done by embedding the null-
character \& in the keyword.
The -j flag does not work for files that contain lines with a single
period (.).
CAUTIONS
The -d flag gets confused in some circumstances, and accepts no date
before 1970.
Links to the RCS and working files are not preserved.
DIAGNOSTICS
The RCS filename, the working filename, and the revision number retrieved
are written to stderr.
EXIT VALUES
2/94 - Intergraph Corporation 7
co(1) CLIX co(1)
The exit value always refers to the last file checked out and is 0 if the
operation was successful, or 1 otherwise.
RELATED INFORMATION
Commands: ci(1), date(1), ident(1), make(1), rcs(1), rcsclean(1),
rcsdiff(1), rcsmerge(1), rlog(1), sccstorcs(1)
Functions: ctime(3)
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.
8 Intergraph Corporation - 2/94