Commit | Line | Data |
---|---|---|
acec9572 WJ |
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 `.'. |