Annotation of src/usr.bin/rcs/rcs.1, Revision 1.30
1.30 ! jmc 1: .\" $OpenBSD: rcs.1,v 1.29 2006/04/19 13:50:38 jmc Exp $
1.1 deraadt 2: .\"
3: .\" Copyright (c) 2005 Jean-Francois Brousseau <jfb@openbsd.org>
1.22 jmc 4: .\" Copyright (c) 2005 Xavier Santolaria <xsa@openbsd.org>
1.1 deraadt 5: .\" All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\"
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. The name of the author may not be used to endorse or promote products
14: .\" derived from this software without specific prior written permission.
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
17: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
18: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
19: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20: .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: .\"
27: .Dd May 16, 2004
28: .Dt RCS 1
29: .Os
30: .Sh NAME
31: .Nm rcs
32: .Nd RCS file management program
33: .Sh SYNOPSIS
34: .Nm
1.20 xsa 35: .Op Fl ehIiLMqTUV
1.14 xsa 36: .Op Fl A Ns Ar oldfile
1.7 niallo 37: .Op Fl a Ns Ar users
38: .Op Fl b Ns Op Ar rev
1.12 xsa 39: .Op Fl c Ns Ar string
1.7 niallo 40: .Op Fl e Ns Op Ar users
1.9 xsa 41: .Op Fl k Ns Ar mode
1.24 ray 42: .Op Fl l Ns Op Ar rev
1.20 xsa 43: .Oo Fl m Ns Ar rev Ns :
44: .Ar msg Oc
1.19 xsa 45: .Op Fl o Ns Ar rev
1.20 xsa 46: .Oo Fl s Ns Ar state Ns
47: .Op : Ns Ar rev Oc
1.14 xsa 48: .Oo Fl t Ns Ar file Ns \*(Ba
49: .Ar str Oc
1.24 ray 50: .Op Fl u Ns Op Ar rev
1.15 xsa 51: .Op Fl x Ns Ar suffixes
1.30 ! jmc 52: .Ar
1.1 deraadt 53: .Sh DESCRIPTION
1.22 jmc 54: Revision Control System (RCS) is a software tool which lets people
55: manage multiple revisions of text that is revised frequently, such as
56: source code or documentation.
57: .Pp
1.1 deraadt 58: The
59: .Nm
60: program is used to create RCS files or manipulate the contents of existing
61: files.
1.22 jmc 62: A set of helper tools is also available:
63: specific revisions of files may be checked in or out, using
64: .Xr ci 1
65: and
66: .Xr co 1 ;
67: differences between revisions viewed or merged, using
68: .Xr rcsdiff 1
69: and
70: .Xr rcsmerge 1 ;
71: and information about RCS files and keyword strings displayed using
72: .Xr rlog 1
73: and
74: .Xr ident 1 .
75: See the respective manual pages for more information
76: about these utilities.
1.1 deraadt 77: .Pp
1.25 jmc 78: .Nm
79: also supports
80: keyword substitution \(en
81: see
82: .Sx KEYWORD SUBSTITUTION ,
83: below, for more information.
84: .Pp
1.1 deraadt 85: The following options are supported:
86: .Bl -tag -width "-e usersXX"
1.14 xsa 87: .It Fl A Ns Ar oldfile
88: Append the access list of
89: .Ar oldfile
90: to the access list of the RCS files.
1.7 niallo 91: .It Fl a Ns Ar users
1.1 deraadt 92: Add the usernames specified in the comma-separated list
93: .Ar users
94: to the access list of the RCS files.
1.7 niallo 95: .It Fl b Ns Op Ar rev
1.14 xsa 96: Set the default branch to
97: .Ar rev .
1.12 xsa 98: .It Fl c Ns Ar string
99: Set comment leader to
100: .Ar string .
1.7 niallo 101: .It Fl e Ns Op Ar users
1.1 deraadt 102: Remove the usernames specified in the comma-separated list
103: .Ar users
104: from the access list of the RCS files.
105: If
106: .Ar users
107: is not specified, all users are removed from the access list.
108: .It Fl h
109: Display the program's usage and exit.
1.20 xsa 110: .It Fl I
111: Interactive mode.
1.1 deraadt 112: .It Fl i
1.10 xsa 113: Create and initialize a new RCS file.
1.11 jmc 114: If the RCS file has no path prefix, try to first create it in the
1.10 xsa 115: .Pa ./RCS
1.11 jmc 116: subdirectory or, if that fails, in the current directory.
1.1 deraadt 117: Files created this way contain no revision.
1.9 xsa 118: .It Fl k Ns Ar mode
119: Specify the keyword substitution mode.
1.1 deraadt 120: .It Fl L
121: Enable strict locking on the RCS files.
1.24 ray 122: .It Fl l Ns Op Ar rev
123: Lock revision
124: .Ar rev
125: on the RCS files.
126: If
127: .Ar rev
128: is not given, the head revision is locked.
1.1 deraadt 129: .It Fl M
130: Disable mail warnings when breaking a user's lock.
131: Normally,
132: .Nm
133: will send a mail to the lock owner when his lock is removed by a call
134: to
135: .Nm
136: .Fl u .
137: This option is currently ignored.
1.7 niallo 138: .It Fl m Ns Ar rev : Ns Ar msg
1.5 jmc 139: Replace revision
140: .Ar rev Ns 's
141: log message with
142: .Ar msg .
1.19 xsa 143: .It Fl o Ns Ar rev
144: Delete one or more revisions.
145: The specifications of the values or revisions are as follows:
146: .Bl -tag -width Ds
147: .It rev
148: Specific revision.
149: .It rev1:rev2
150: Delete all revisions of a branch between
151: .Ar rev1
152: and
153: .Ar rev2 .
154: .It rev1::rev2
155: Delete all revisions of a branch between
156: .Ar rev1
157: and
158: .Ar rev2
159: without deleting revisions
160: .Ar rev1
161: and
162: .Ar rev2 .
163: .It :rev
164: Delete all revisions of the branch until revision
165: .Ar rev .
166: .It rev:
167: Delete all revisions of the branch from revision
168: .Ar rev
169: until the last revision of the branch.
170: .El
1.13 xsa 171: .It Fl q
172: Be quiet about reporting.
1.14 xsa 173: .Sm off
1.20 xsa 174: .It Fl s Ar state Op : Ar rev
175: .Sm on
176: Sets the state of revision
177: .Ar rev
178: to the identifier
179: .Ar state .
180: The specified value may not contain a space character.
181: If
182: .Ar rev
183: is not specified, the latest revision of the default branch
184: is assumed.
1.16 xsa 185: .It Fl T
1.17 jmc 186: Preserve the modification time of RCS files.
1.20 xsa 187: .Sm off
1.14 xsa 188: .It Fl t Ar file \*(Ba Ar str
189: .Sm on
190: Change the descriptive text.
191: The descriptive text is taken from the
192: .Ar file
193: specified as argument or from the string
194: .Ar str
195: given as argument if it is preceded by the
196: .Sq -
197: character.
198: If no argument is used, the descriptive text is taken from standard input
199: terminated by end-of-file or by a line containing the
200: .Sq \&.
201: character by itself.
1.1 deraadt 202: .It Fl U
203: Disable strict locking on the RCS files.
1.24 ray 204: .It Fl u Ns Op Ar rev
205: Unlock revision
206: .Ar rev
207: on the RCS files.
208: If
209: .Ar rev
210: is not given, the head revision is unlocked.
1.1 deraadt 211: .It Fl V
212: Print the program's version string and exit.
1.15 xsa 213: .It Fl x Ns Ar suffixes
214: Specifies the suffixes for RCS files.
215: Suffixes should be separated by the
216: .Sq /
217: character.
1.25 jmc 218: .El
219: .Sh KEYWORD SUBSTITUTION
220: As long as you edit source files inside a working directory you
221: can always find out the state of your files via the
1.27 jmc 222: .Xr cvs 1
1.25 jmc 223: .Ic status
224: or
225: .Ic log
226: commands, but as soon as files get exported from
227: your local working copy, it becomes harder to identify which
228: revisions they are.
229: .Pp
230: .Nm
231: and
232: .Xr cvs 1
233: can use a mechanism known as
234: .Sq keyword substitution
235: to help identify the files.
236: Embedded strings of the form $keyword$ and $keyword:...$ in a file
237: are replaced with strings of the form $keyword: value$ whenever you
238: obtain a new revision of the file.
239: The possible keywords are as follows:
1.30 ! jmc 240: .Bl -tag -width "XrevisionXX" -offset "XXX"
1.25 jmc 241: .It $\&Author$
242: The name of the user who checked in the revision.
243: .It $\&Date$
244: The date and hour (UTC) the revision was checked in.
245: .It $\&Header$
246: Standard header containing the full pathname of the RCS
247: file, the revision number, the date (UTC), the author and the state.
248: .It $\&Id$
249: The same content as $\&Header$ but without the path
250: of the RCS file.
251: .It $\&Log$
252: The log message supplied during commit, preceded by a header
253: containing the RCS filename, the revision number, the
254: author, and the date (UTC).
255: .It $\&Name$
256: The tag name used to check out the file.
257: .It $\&RCSfile$
258: The name of the RCS file, but without a path.
259: .It $\&Revision$
260: The revision number assigned to the revision.
261: .It $\&Source$
262: The full pathname of the RCS file.
263: .It $\&State$
264: The state assigned to the revision.
265: .El
266: .Pp
267: Keyword substitution has its disadvantages: sometimes the
268: literal text string $\&Author$ is wanted inside a file without
269: .Nm
1.27 jmc 270: or
271: .Xr cvs 1
1.25 jmc 272: interpreting it as a keyword and expanding it into something like
273: $\&Author$.
274: The
1.26 jmc 275: .Fl k Ns Ar o
1.25 jmc 276: option can be used to turn off keyword substitution entirely though.
277: There is unfortunately no way to selectively turn off keyword substitution.
278: .Pp
279: Each file and working directory copy of a file have a stored
280: default substitution mode.
281: Substitution modes on files are set by the
282: .Fl k Ns Ar mode
283: option.
284: .Pp
285: The possible substitution modes are as follows:
286: .Bl -tag -width Ds -offset 3n
1.26 jmc 287: .It Fl k Ns Ar b
1.25 jmc 288: Like
1.26 jmc 289: .Fl k Ns Ar o ,
1.25 jmc 290: but also avoids the conversion of line endings.
291: This option is used to handle binary files.
1.26 jmc 292: .It Fl k Ns Ar k
1.25 jmc 293: Does not substitute the keywords.
294: Useful with the
1.27 jmc 295: .Xr cvs 1
1.25 jmc 296: .Ic diff
1.28 jmc 297: and
298: .Xr rcsdiff 1
299: commands to avoid displaying the differences between keyword substitutions.
1.26 jmc 300: .It Fl k Ns Ar kv
1.25 jmc 301: The default behaviour.
302: Keywords are normally substituted i.e. $\&Revision$ becomes
303: $\&Revision: 1.1 $.
1.26 jmc 304: .It Fl k Ns Ar kvl
1.25 jmc 305: Like
1.26 jmc 306: .Fl k Ns Ar kv ,
1.25 jmc 307: except that the locker's name is displayed along with the version
308: if the given revision is currently locked.
309: This option is normally not useful as
310: .Nm
1.27 jmc 311: and
312: .Xr cvs 1
313: do not use file locking by default.
1.26 jmc 314: .It Fl k Ns Ar o
1.25 jmc 315: No substitutions are done.
316: This option is often used with the
1.27 jmc 317: .Xr cvs 1
1.25 jmc 318: .Ic import
319: command to guarantee that files that already contain external keywords
320: do not get modified.
1.26 jmc 321: .It Fl k Ns Ar v
1.25 jmc 322: Substitute the value of keywords instead of keywords themselves
323: e.g. instead of $\&Revision$, only insert 1.1 and not $\&Revision: 1.1 $.
324: This option must be used with care, as it can only be used once.
325: It is often used with the
1.27 jmc 326: .Xr cvs 1
1.25 jmc 327: .Ic export
328: command to freeze the values before releasing software.
1.1 deraadt 329: .El
330: .Sh ENVIRONMENT
331: .Bl -tag -width RCSINIT
332: .It Ev RCSINIT
333: If set, this variable should contain a list of space-delimited options that
334: are prepended to the argument list.
335: .El
1.22 jmc 336: .Sh EXAMPLES
337: One of the most common uses of
338: .Nm
339: is to track changes to a document containing source code.
340: .Pp
341: As an example,
342: we'll look at a user wishing to track source changes to a file
343: .Ar foo.c .
344: .Pp
345: If the
346: .Ar RCS
347: directory does not exist yet, create it as follows and invoke the
348: check-in command:
349: .Bd -literal -offset indent
350: $ mkdir RCS
351: $ ci foo.c
352: .Ed
353: .Pp
354: This command creates an RCS file
355: .Ar foo.c,v
356: in the
357: .Ar RCS
358: directory, stores
359: .Ar foo.c
360: into it as revision 1.1, and deletes
361: .Ar foo.c .
362: .Xr ci 1
363: will prompt for a description of the file to be entered.
364: Whenever a newly created (or updated) file is checked-in,
365: .Xr ci 1
366: will prompt for a log message to be entered which should summarize
367: the changes made to the file.
368: That log message will be added to the RCS file along with the new revision.
369: .Pp
370: The
371: .Xr co 1
372: command can now be used to obtain a copy of the checked-in
373: .Ar foo.c,v
374: file:
375: .Pp
376: .Dl $ co foo.c
377: .Pp
378: This command checks the file out in shared or unlocked mode.
379: If a user wants to have exclusive access to the file to make changes to it,
380: it needs to be checked out in locked mode using the
381: .Fl l
382: option of the
383: .Xr co 1
384: command.
385: Only one concurrent locked checkout of a revision is permitted.
386: .Pp
387: Once changes have been made to the
388: .Pa foo.c
389: file, and before checking the file in, the
390: .Xr rcsdiff 1
391: command can be used to view changes between the working file
392: and the most recently checked-in revision:
393: .Pp
394: .Dl $ rcsdiff -u foo.c
395: .Pp
396: The
397: .Fl u
398: option produces a unified diff.
399: See
400: .Xr diff 1
401: for more information.
1.1 deraadt 402: .Sh SEE ALSO
403: .Xr ci 1 ,
404: .Xr co 1 ,
1.3 jmc 405: .Xr ident 1 ,
1.1 deraadt 406: .Xr rcsclean 1 ,
407: .Xr rcsdiff 1 ,
1.8 xsa 408: .Xr rcsmerge 1 ,
1.6 xsa 409: .Xr rlog 1
1.21 jmc 410: .Sh STANDARDS
411: The flag
412: .Op Fl z
413: has no effect and is provided
414: for compatibility only.
1.29 jmc 415: .Sh CAVEATS
416: For historical reasons,
417: the RCS tools do not permit whitespace between options and their arguments.