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