co(1) co(1)
NAME
co - check out RCS revisions
SYNOPSIS
co [-l[rev]] [-p[rev]] [-q[rev]] [-ddate] [-r[rev]] [-
sstate] [-w[login]] [-jjoinlist] files
DESCRIPTION
co retrieves revisions from RCS files. Each filename ending
in ,v is taken to be an RCS file. All other files are as-
sumed to be working files. co retrieves a revision from
each RCS file and stores it in the corresponding working
file.
Pairs of RCS files and working files may be specified in
three ways (see the EXAMPLES section later in this entry).
(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 suffix ,v.
(3) Only the working file is given. Then the name of the
RCS file is derived from the name of the working file
by removing path2/ and appending the suffix ,v.
If the RCS file is omitted or specified without a path, then
co looks for the RCS file, first in the directory ./RCS and
then in the current directory.
Revisions of an RCS file may be checked-out locked or un-
locked. Locking a revision prevents overlapping updates. A
revision checked out for reading or processing (for example,
compiling) need not be locked. A revision checked out for
editing and later check-in must normally be locked. Locking
a revision currently locked by another user fails. (A lock
may be broken with the rcs(1) command.) co with locking re-
quires the caller to be on the access list of the RCS file,
unless he is the owner of the file or the superuser, or the
access list is empty. co without locking is not subject to
access-list restrictions.
A revision is selected by number, check-in date/time, au-
thor, or state. If none of these options is specified, the
latest revision on the trunk is retrieved. When the options
are applied in combination, the latest revision that satis-
April, 1990 1
co(1) co(1)
fies all of them is retrieved. The options for date/time,
author, and state, retrieve a revision on the selected
branch. The selected branch is either derived from the re-
vision number (if given) or is the highest branch on the
trunk. A revision number may be attached to one of the op-
tions -l, -p, -q, or -r.
A co command applied to an RCS file with no revisions
creates a zero-length file. co always performs keyword sub-
stitution, as follows.
FLAG OPTIONS
-l[rev] Locks the checked-out revision for the caller.
If omitted, the checked-out revision is not
locked. See option -r for handling of the revi-
sion number rev.
-p[rev] Prints the retrieved revision on the standard
output rather than storing it in the working
file. This option is useful when co is part of a
pipe.
-q[rev] Quiet mode; diagnostics are not printed.
-ddate Retrieves the latest revision on the selected
branch whose checkin date/time is less than or
equal to date. The date and time may be given in
free format and are converted to local time. Ex-
amples of acceptable formats for date are:
22-April-1985, 17:20-CDT
2:25 AM, Dec. 29, 1987
Tue-PDT, 1986, 4pm Jul 21
Fri Apr 16 15:52:25 EST 1988
The last example illustrates the format produced
by ctime(3) and date(1). Most fields in the date
and time may be defaulted. co determines the de-
faults in this order: year, month, day, hour,
minute, and second (that is, from most to least
significant). At least one of these fields must
be provided. For omitted fields that are of
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 de-
faults to 10:30:00 of the 20th of the current
month and current year. The date specified on
the command line must be in quotation marks if it
contains spaces.
-r[rev] retrieves the latest revision whose number is
2 April, 1990
co(1) co(1)
less than or equal to rev. If rev indicates a
branch rather than a revision, the latest revi-
sion on that branch is retrieved. rev is com-
posed of one or more numeric or symbolic fields
separated by a period, (.). The numeric
equivalent of a symbolic field is specified with
the -n option of the commands ci and rcs.
-sstate retrieves the latest revision on the selected
branch whose state is set to state.
-w[login] retrieves the latest revision on the selected
branch which was checked in by the user with lo-
gin name login. If the argument login is omit-
ted, the caller's login name is assumed.
-jjoinlist generates a new revision which is the join of the
revisions on joinlist. The joinlist is a comma-
separated list of pairs of the form rev2:rev3,
where rev2 and rev3 are (symbolic or numeric) re-
vision numbers. For the initial pair, rev1
denotes the revision selected by the options -
l,...,-w. 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 particularly useful
if rev1 and rev3 are the ends of two branches
that have rev2 as a common ancestor. If rev1 <
rev2 < rev3 are on the same branch, joining gen-
erates a new revision which is like rev3, but
with all changes that lead from rev1 to rev2 un-
done. If changes from rev2 to rev1 overlap with
changes from rev2 to rev3, co prints 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 of the
arguments indicate branches, the latest revisions
on those branches are assumed. If the option -l
is present, the initial rev1 is locked.
KEYWORD SUBSTITUTION
Strings of the form $keyword$ and $keyword:...$ embedded in
the text are replaced with strings of the form $keyword:
value $, where keyword and value are pairs as listed. Key-
April, 1990 3
co(1) co(1)
words may be embedded in literal strings or comments to
identify a revision.
Initially, the user enters strings of the form $keyword$.
On checkout, co replaces these strings with strings that are
of the form $keyword: value $. If a revision containing
strings of the latter form is checked back in, the value
fields will be replaced during the next checkout. Thus, the
keyword values are automatically updated on checkout.
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 RCS filename,
the revision number, the date, the author, and
the state.
$Locker$ The login name of the user who locked the revi-
sion (empty if not locked).
$Log$ The log message supplied during checkin, pre-
ceded by a header containing the RCS filename,
the revision number, the author, and the date.
Existing log messages are not replaced. In-
stead, the new log message is inserted after
$Log:... $. This is useful for accumulating a
complete change log in a source file.
$Revision$ The revision number assigned to the revision.
$Source$ The full pathname of the RCS file.
$State$ The state assigned to the revision with rcs -s
or ci -s.
DIAGNOSTICS
The RCS filename, the working filename, and the revision
number retrieved are written to the diagnostic output. The
exit status always refers to the last file checked out, and
is 0 if the operation was successful, 1 if otherwise.
EXAMPLES
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
into io.c.
co io.c
4 April, 1990
co(1) co(1)
co RCS/io.c,v
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
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 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 already exists
and has write permission, co cancels the checkout if -q is
given, or asks whether to cancel if -q is not given. If the
existing working file is not writable, it is deleted before
the checkout.
FILES
The caller of the command must have write permission in the
working directory, read permission for the RCS file, and ei-
ther read permission (for reading) or read/write permission
(for locking) in the directory which 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 updates.
DISCLAIMER
This reference manual entry describes a utility that Apple
understands to have been released into the public domain by
its author or authors. Apple has included this public
domain utility for your convenience. Use it at your own
discretion. Often the source code can be obtained if addi-
tional requirements are met, such as the purchase of a site
license from an author or institution.
IDENTIFICATION
Author: Walter F. Tichy, Purdue University, West Lafayette,
IN 47907.
c
Copyright 1982 by Walter F. Tichy.
SEE ALSO
ci(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1),
rcsmerge(1), rlog(1), rcsfile(4), sccstorcs(1M).
Walter F. Tichy, ``Design, Implementation, and Evaluation of
a Revision Control System,'' in Proceedings of the 6th
International Conference on Software Engineering, IEEE, Tok-
yo, Sept. 1982.
April, 1990 5
LIMITATIONS
The option -d gets confused in some circumstances and ac-
cepts no date before 1970. There is no way to suppress the
expansion of keywords, except by writing them differently.
In nroff and troff, this is done by embedding the null-
character \& into the keyword.
BUGS
The option -j does not work for files that contain lines
with a single ..
6 April, 1990