![[Previous]](../prev.gif) |
![[Contents]](../contents.gif) |
![[Next]](../next.gif) |
|
|
|
Check out RCS revisions (UNIX)
co [options] file...
The co 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).
Since further keyword substitution can't be performed once the keyword names are removed, you should use this option with care. Because keywords could be lost, this option can't be combined with -l. The option also turns off the owner write permission of the working file. To edit the file later, check it out again without -kv.
A revision 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 option of the ci and rcs commands.
The -z option does not affect dates stored in RCS files, which are always UTC.
The co utility retrieves a revision from each RCS file and stores it into the corresponding working file. Each filename ending in ,v is taken 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.
The RCS filename, the working filename, and the revision number retrieved are written to the diagnostic output.
You can specify files in the same way that you specify files for the ci utility:
As in ci, if the RCS file is specified without a path in 1. and 2., then co looks for the RCS file first in the directory ./RCS and then in the current directory (this also applies to ci).
Revisions of an RCS file may be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision checked out for reading or processing (e.g. compiling) need not be locked. A revision checked out for editing and later checkin must be locked. Checkout with locking fails if the revision to be checked out is currently locked by another user (a lock may be broken with rcs). Checkout with locking also requires the caller to be on the access list of the RCS file, unless either of the following is true:
Checkout without locking isn't subject to access list restrictions and isn't affected by the presence of locks.
A revision is selected by options for revision or branch number, checkin date/time, author, or state. When you combine several selection options, co retrieves the latest revision that satisfies all of them. If no selection option is specified, co retrieves the latest revision on the default branch (normally the trunk, see the -b option of rcs). You can attach a revision or branch number to any of the options -f, -I, -l, -p, -q, -r, or -u. The options -d (date), -s (state), and -w (author) retrieve from either of the following:
A co command applied to an RCS file with no revisions creates a zero-length working file.
To see which version of RCS your correspondents are running, have them invoke rlog on an RCS file. The following table shows you what to look for:
| If: | Version is: |
|---|---|
| None of the first few lines of output contain the string branch | 3 |
| The dates' years have just two digits | 4 |
| Neither of the above is true | 5 |
Also note the following:
When you specify date and time through option -d, remember that time zone LT stands for local time. Note also that other common time zone names are understood. For example, the following dates are equivalent if local time is January 11, 1997, 8 pm Pacific Standard Time (eight hours west of UTC):
8:00 pm LT 4:00 AM, Jan. 12, 1997 1997/01/12 04:00:00 Thu Jan 11 20:00:00 1997 LT Thu Jan 11 20:00:00 PST 1997 Fri Jan 12 04:00:00 UTC 1997 Thu, 11 Jan 1997 20:00:00 -0800 Fri-JST, 1997, 1pm Jan 12 12-January-1997, 04:00-WET
Most fields in the date and time may be defaulted. The default time zone is UTC. The other defaults are determined in the order year, month, day, hour, minute, and second (most- to least-significant). You must provide at least one of these fields. For omitted fields that are of higher significance than the highest provided field, the time zone's 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 UTC time zone's current month and year. You must quote the date/time if there are spaces.
The co utility always performs keyword substitution. Strings of the form $keyword$ and $keyword:...$ embedded in the text are replaced with strings of the form $keyword:value$ listed below. Note that you can embed keywords in literal strings or comments to identify a revision.
Initially, you enter strings of the form $keyword$. On checkout, co replaces these strings with strings 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. This automatic substitution can be modified by the -k options.
The following table lists the keywords and their corresponding values:
| Keyword | Corresponding value |
|---|---|
| $Author$ | The login name of the user who checked in the revision. |
| $Date$ | The date and time (UTC) the revision was checked in. |
| $Header$ | A standard header containing the full pathname of the RCS file, the revision number, the date (UTC), the author, the state, and the locker (if locked). |
| $Id$ | (same as $Header$, except that the RCS filename is without a 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 (UTC). Existing log messages aren't 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 a path. |
| $Revision$ | The revision number assigned to the revision. |
| $Source$ | The full pathname of the RCS file. |
| $State$ | The state assigned to the revision with the -s option of rcs or ci. |
You can use the -jjoinlist option to generate a revision that is the join of several other revisions. The joinlist is a list of pairs, separated by commas; each pair is of the form:
where rev2 and rev3 are (symbolic or numeric) revision numbers. For the initial such pair, rev1 denotes the revision selected by options -f, ..., -w. For all other pairs, rev1 denotes the revision generated by the previous pair. (Thus, the output of one join becomes the input of 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 generates a new revision that's like rev3, but with all changes that lead from rev1 to rev2 undone. If changes from rev2 to rev1 overlap with changes from rev2 to rev3, co prints a warning and includes the overlapping sections, delimited by these lines:
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. The options -l and -u lock or unlock rev1.
The working file inherits the read and execute permissions from the RCS file. In addition, the owner write permission is turned on, unless either of the following is true:
If a file with the name of the working file already exists and has write permission, co asks if it can delete the existing writable file. If the existing working file isn't writable or -f is given, the working file is deleted without asking.
Let's say the current directory contains a subdirectory RCS with an RCS file io.c,v. All of the following commands would retrieve the latest revision from RCS/io.c,v and store it into io.c:
co io.c
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
The co utility accesses files much as ci does, except that it doesn't need to read the working file.
The exit status is zero only if all operations were successful.
GNU
The -d option sometimes gets confused. In addition, it accepts no date before 1970.
Links to the RCS files and working files aren't preserved.
There's no way to selectively suppress the expansion of keywords, except by writing them differently. This is done by embedding another character into the keyword.
ci, date, 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.
|
|
|