![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to co.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man|
Return to co.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man |
1.1 root 1: .TH CO 1L "" "Purdue University"
2: .SH NAME
3: co \- check out RCS revisions
4: .SH SYNOPSIS
5: .B co
6: [ options ]
7: file ...
8: .SH DESCRIPTION
9: .I Co
10: retrieves a revision from each RCS file and stores it into
11: the corresponding working file.
12: Each file name ending in `,v' is taken to be an RCS file;
13: all other files are assumed to be working files.
14: If only a working file is given, \fIco\fR tries to find the corresponding
15: RCS file in the directory ./RCS and then in the current directory.
16: For more details, see the file naming section below.
17: .PP
18: Revisions of an RCS file may be checked out locked or unlocked. Locking a
19: revision prevents overlapping updates. A revision checked out for reading or
20: processing (e.g., compiling) need not be locked. A revision checked out
21: for editing and later checkin must normally be locked. \fICo\fR with locking
22: fails if the revision to be checked out is currently locked by another user.
23: (A lock may be broken with the
24: .IR rcs (1L)
25: command.)
26: \fICo\fR with locking also requires the caller to be on the access list of
27: the RCS file, unless he is the owner of the
28: file or the superuser, or the access list is empty.
29: \fICo\fR without locking is not subject to accesslist restrictions, and is
30: not affected by the presence of locks.
31: .PP
32: A revision is selected by options for revision or branch number,
33: checkin date/time, author, or state.
34: When the selection options
35: are applied in combination, \fIco\fR retrieves the latest revision
36: that satisfies all of them.
37: If none of the selection options
38: is specified, \fIco\fR retrieves the latest revision
39: on the default branch (normally the trunk, see the
40: .B \-b
41: option of
42: .IR rcs (1L)).
43: A revision or branch number may be attached
44: to any of the options
45: \fB\-f\fR, \fB\-l\fR, \fB\-p\fR, \fB\-q\fR, \fB\-r\fR, or \fB\-u\fR.
46: The options \fB\-d\fR (date), \fB\-s\fR (state), and \fB\-w\fR (author)
47: retrieve from a single branch, the \fIselected\fR branch,
48: which is either specified by one of
49: \fB\-f\fR,..., \fB\-u\fR, or the default branch.
50: .PP
51: A \fIco\fR command applied to an RCS
52: file with no revisions creates a zero-length working file.
53: \fICo\fR always performs keyword substitution (see below).
54: .PP
55: .TP 11
56: .BR \-r [\fIrev\fR]
57: retrieves the latest revision whose number is less than or equal to \fIrev\fR.
58: If \fIrev\fR indicates a branch rather than a revision,
59: the latest revision on that branch is retrieved.
60: If \fIrev\fR is omitted, the latest revision on the default branch
61: (see the
62: .B \-b
63: option of
64: .IR rcs (1L))
65: is retrieved.
66: \fIRev\fR is composed of one or more numeric or symbolic fields
67: separated by `.'. The numeric equivalent of a symbolic field
68: is specified with the \fB\-n\fR option of the commands
69: .IR ci (1L)
70: and
71: .IR rcs (1L).
72: .TP 11
73: .BR \-l [\fIrev\fR]
74: same as \fB\-r\fR, except that it also locks the retrieved revision for
75: the caller. See option \fB\-r\fR for handling of the revision number
76: .I rev .
77: .TP 11
78: .BR \-u [\fIrev\fR]
79: same as \fB\-r\fR, except that it unlocks the retrieved revision (if it was
80: locked by the caller). If \fIrev\fR is omitted, \fB\-u\fR
81: retrieves the latest revision locked by the caller; if no such lock exists,
82: it retrieves the latest revision on the default branch.
83: .TP 11
84: .BR \-f [\fIrev\fR]
85: forces the overwriting of the working file;
86: useful in connection with \fB\-q\fR.
87: See also the section on file modes below.
88: .TP 11
89: .BR \-p [\fIrev\fR]
90: prints the retrieved revision on the standard output rather than storing it
91: in the working file.
92: This option is useful when \fIco\fR
93: is part of a pipe.
94: .TP 11
95: .BR \-q [\fIrev\fR]
96: quiet mode; diagnostics are not printed.
97: .TP 11
98: .BI \-d "date"
99: retrieves the latest revision on the selected branch whose checkin date/time is less than or equal to \fIdate\fR.
100: The date and time may be given in free format and are converted to local time.
101: Examples of formats for \fIdate\fR:
102: .ne 5
103: .nf
104:
105: \fI22-April-1982, 17:20-CDT,
106: 2:25 AM, Dec. 29, 1983,
107: Tue-PDT, 1981, 4pm Jul 21\fR \fR(free format),
108: \fIFri, April 16 15:52:25 EST 1982 \fR(output of ctime).
109: .fi
110:
111: Most fields in the date and time may be defaulted.
112: \fICo\fR determines the defaults in the order year, month, day,
113: hour, minute, and second (most to least significant). At least one of these
114: fields must be provided. For omitted fields that are of higher significance
115: than the highest provided field,
116: the current values are assumed. For all other omitted fields,
117: the lowest possible values are assumed.
118: For example, the date "20, 10:30" defaults to
119: 10:30:00 of the 20th of the current month and current year.
120: The date/time must be quoted if it contains spaces.
121: .TP 11
122: .BI \-s "state"
123: retrieves the latest revision on the selected branch whose state is set to \fIstate\fR.
124: .TP 11
125: .BR \-w [\fIlogin\fR]
126: retrieves the latest revision on the selected branch which was checked in
127: by the user with login name \fIlogin\fR. If the argument \fIlogin\fR is
128: omitted, the caller's login is assumed.
129: .TP 11
130: .BI \-j joinlist
131: generates a new revision which is the join of the revisions on \fIjoinlist\fR.
132: \fIJoinlist\fR is a comma-separated list of pairs of the form
133: \fIrev2:rev3\fR, where \fIrev2\fR and \fIrev3\fR are (symbolic or numeric)
134: revision numbers.
135: For the initial such pair, \fIrev1\fR denotes the revision selected
136: by the above options \fB\-r\fR, ..., \fB\-w\fR. For all other pairs, \fIrev1\fR
137: denotes the revision generated by the previous pair. (Thus, the output
138: of one join becomes the input to the next.)
139:
140: For each pair, \fIco\fR joins revisions \fIrev1\fR and \fIrev3\fR
141: with respect to \fIrev2\fR.
142: This means that all changes that transform
143: \fIrev2\fR into \fIrev1\fR are applied to a copy of \fIrev3\fR.
144: This is particularly useful if \fIrev1\fR
145: and \fIrev3\fR are the ends of two branches that have \fIrev2\fR as a common
146: ancestor. If \fIrev1\fR < \fIrev2\fR < \fIrev3\fR on the same branch,
147: joining generates a new revision which is like \fIrev3\fR, but with all
148: changes that lead from \fIrev1\fR to \fIrev2\fR undone.
149: If changes from \fIrev2\fR to \fIrev1\fR overlap with changes from
150: \fIrev2\fR to \fIrev3\fR, \fIco\fR prints a warning and includes the
151: overlapping sections, delimited by the lines \fI<<<<<<<\ rev1,
152: =======\fR, and \fI>>>>>>>\ rev3\fR.
153:
154: For the initial pair, \fIrev2\fR may be omitted. The default is the common
155: ancestor.
156: If any of the arguments indicate branches, the latest revisions
157: on those branches are assumed.
158: The options \fB\-l\fR and \fB\-u\fR lock or unlock \fIrev1\fR.
159: .SH "KEYWORD SUBSTITUTION"
160: Strings of the form \fI$keyword$\fR and \fI$keyword:...$\fR embedded in
161: the text are replaced
162: with strings of the form \fI$keyword:\ value\ $\fR,
163: where \fIkeyword\fR and \fIvalue\fR are pairs listed below.
164: Keywords may be embedded in literal strings
165: or comments to identify a revision.
166: .PP
167: Initially, the user enters strings of the form \fI$keyword$\fR.
168: On checkout, \fIco\fR replaces these strings with strings of the form
169: \fI$keyword:\ value\ $\fR. If a revision containing strings of the latter form
170: is checked back in, the value fields will be replaced during the next
171: checkout.
172: Thus, the keyword values are automatically updated on checkout.
173: .PP
174: Keywords and their corresponding values:
175: .TP 13
176: $\&Author$
177: The login name of the user who checked in the revision.
178: .TP
179: $\&Date$
180: The date and time the revision was checked in.
181: .TP
182: $\&Header$
183: A standard header containing the full pathname of the RCS file, the
184: revision number, the date, the author, the state, and the locker (if locked).
185: .TP
186: $\&Id$
187: Same as $\&Header$, except that the RCS file name is without a path.
188: .TP
189: $\&Locker$
190: The login name of the user who locked the revision (empty if not locked).
191: .TP
192: $\&Log$
193: The log message supplied during checkin, preceded by a header
194: containing the RCS file name, the revision number, the author, and the date.
195: Existing log messages are NOT replaced.
196: Instead, the new log message is inserted after \fI$\&Log:...$\fR.
197: This is useful for
198: accumulating a complete change log in a source file.
199: .TP
200: $\&RCSfile$
201: The name of the RCS file without path.
202: .TP
203: $\&Revision$
204: The revision number assigned to the revision.
205: .TP
206: $\&Source$
207: The full pathname of the RCS file.
208: .TP
209: $\&State$
210: The state assigned to the revision with the
211: .B \-s
212: option of
213: .IR rcs (1L)
214: or
215: .IR ci (1L).
216: .TP
217: .SH "FILE NAMING"
218: Pairs of RCS files and working files may be specified in 3 ways (see also the
219: example section).
220: .PP
221: 1) Both the RCS file and the working file are given. The RCS file name is of
222: the form \fIpath1/workfile,v\fR
223: and the working file name is of the form
224: \fIpath2/workfile\fR, where
225: \fIpath1/\fR and
226: \fIpath2/\fR are (possibly different or empty) paths and
227: \fIworkfile\fR is a file name.
228: .PP
229: 2) Only the RCS file is given. Then the working file is created in the current
230: directory and its name is derived from the name of the RCS file
231: by removing \fIpath1/\fR and the suffix \fI,v\fR.
232: .PP
233: 3) Only the working file is given.
234: Then \fIco\fR looks for an RCS file of the form
235: \fIpath2/RCS/workfile,v\fR or \fIpath2/workfile,v\fR (in this order).
236: .PP
237: If the RCS file is specified without a path in 1) and 2), then \fIco\fR
238: looks for the RCS file first in the directory ./RCS and then in the current
239: directory.
240: .SH EXAMPLES
241: Suppose the current directory contains a subdirectory `RCS' with an RCS file
242: `io.c,v'. Then all of the following commands retrieve the latest
243: revision from `RCS/io.c,v' and store it into `io.c'.
244: .nf
245: .sp
246: co io.c; co RCS/io.c,v; co io.c,v;
247: co io.c RCS/io.c,v; co io.c io.c,v;
248: co RCS/io.c,v io.c; co io.c,v io.c;
249: .fi
250: .SH "FILE MODES"
251: The working file inherits the read and execute permissions from the RCS
252: file. In addition, the owner write permission is turned on, unless the file
253: is checked out unlocked and locking is set to \fIstrict\fR (see
254: .IR rcs (1L)).
255: .PP
256: If a file with the name of the working file exists already and has write
257: permission, \fIco\fR aborts the checkout if \fB\-q\fR is given, or asks
258: whether to abort if \fB\-q\fR is not given. If the existing working file is
259: not writable or \fB\-f\fR is given, the working file is deleted without asking.
260: .SH FILES
261: The caller of the command must have write permission in the working
262: directory, read permission for the RCS file, and either read permission
263: (for reading) or read/write permission (for locking) in the directory which
264: contains the RCS file.
265: .PP
266: A number of temporary files are created.
267: A semaphore file is created in the directory of the RCS file
268: to prevent simultaneous update.
269: .SH DIAGNOSTICS
270: The RCS file name, the working file name,
271: and the revision number retrieved are
272: written to the diagnostic output.
273: The exit status always refers to the last file checked out,
274: and is 0 if the operation was successful, 1 otherwise.
275: .SH IDENTIFICATION
276: .de VL
277: \\$2
278: ..
279: Author: Walter F. Tichy,
280: Purdue University, West Lafayette, IN, 47907.
281: .sp 0
282: Revision Number:
283: .VL $Revision: 1.4 $
284: ; Release Date:
285: .VL $Date: 89/05/02 11:20:22 $
286: \&.
287: .sp 0
288: Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
289: .SH SEE ALSO
290: ci(1L), ident(1L), rcs(1L), rcsdiff(1L), rcsintro(1L), rcsmerge(1L), rlog(1L),
291: rcsfile(5L)
292: .sp 0
293: Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control
294: System," in \fIProceedings of the 6th International Conference on Software
295: Engineering\fR, IEEE, Tokyo, Sept. 1982.
296: .SH LIMITATIONS
297: The option \fB\-d\fR gets confused in some circumstances,
298: and accepts no date before 1970.
299: Links to the RCS and working files are not preserved.
300: There is no way to suppress the expansion of keywords, except
301: by writing them differently. In nroff and troff, this is done by embedding the
302: null-character `\\&' into the keyword.
303: .SH BUGS
304: The option \fB\-j\fR does not work for
305: files that contain lines with a single `.'.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.