Annotation of src/usr.bin/rcs/rcs.1, Revision 1.42
1.42 ! jmc 1: .\" $OpenBSD: rcs.1,v 1.41 2006/04/27 10:19:23 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.42 ! jmc 35: .Op Fl eIiLqTUV
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.33 jmc 43: .Oo Fl m Ns Ar rev :
1.20 xsa 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.39 jmc 78: Files may be selected by
79: .Em revision
80: or, where no revision is specified,
1.34 jmc 81: the latest revision of the default branch is used.
82: Revisions are specified either by using the
83: .Fl r
84: option or
85: by appending the revision number to any option that supports it.
1.38 jmc 86: .Pp
87: .Nm
88: supports the notion of
89: .Em state .
90: The state is an arbitrary string of characters used to describe a file
91: (or a specific revision of a file).
92: States can be set or changed using the
93: .Fl s
94: option, for RCS tools which support it.
95: The state of a file/revision can be modified without having to check in
96: a new file/revision.
97: The default state is
98: .Sq Exp
99: (Experimental).
100: Examples of states could be
101: .Sq Dev ,
102: .Sq Reviewed ,
103: or
104: .Sq Stab .
1.34 jmc 105: .Pp
1.25 jmc 106: .Nm
107: also supports
108: keyword substitution \(en
109: see
110: .Sx KEYWORD SUBSTITUTION ,
111: below, for more information.
112: .Pp
1.1 deraadt 113: The following options are supported:
114: .Bl -tag -width "-e usersXX"
1.14 xsa 115: .It Fl A Ns Ar oldfile
116: Append the access list of
117: .Ar oldfile
118: to the access list of the RCS files.
1.7 niallo 119: .It Fl a Ns Ar users
1.1 deraadt 120: Add the usernames specified in the comma-separated list
121: .Ar users
122: to the access list of the RCS files.
1.7 niallo 123: .It Fl b Ns Op Ar rev
1.14 xsa 124: Set the default branch to
125: .Ar rev .
1.12 xsa 126: .It Fl c Ns Ar string
127: Set comment leader to
128: .Ar string .
1.41 jmc 129: The comment leader specifies the comment character(s) for a file.
130: This option is useful for compatibility with older RCS implementations
131: only.
1.7 niallo 132: .It Fl e Ns Op Ar users
1.1 deraadt 133: Remove the usernames specified in the comma-separated list
134: .Ar users
135: from the access list of the RCS files.
136: If
137: .Ar users
138: is not specified, all users are removed from the access list.
1.20 xsa 139: .It Fl I
140: Interactive mode.
1.1 deraadt 141: .It Fl i
1.10 xsa 142: Create and initialize a new RCS file.
1.11 jmc 143: If the RCS file has no path prefix, try to first create it in the
1.10 xsa 144: .Pa ./RCS
1.11 jmc 145: subdirectory or, if that fails, in the current directory.
1.1 deraadt 146: Files created this way contain no revision.
1.9 xsa 147: .It Fl k Ns Ar mode
148: Specify the keyword substitution mode.
1.1 deraadt 149: .It Fl L
150: Enable strict locking on the RCS files.
1.24 ray 151: .It Fl l Ns Op Ar rev
152: Lock revision
153: .Ar rev
154: on the RCS files.
1.7 niallo 155: .It Fl m Ns Ar rev : Ns Ar msg
1.5 jmc 156: Replace revision
157: .Ar rev Ns 's
158: log message with
159: .Ar msg .
1.19 xsa 160: .It Fl o Ns Ar rev
161: Delete one or more revisions.
162: The specifications of the values or revisions are as follows:
163: .Bl -tag -width Ds
164: .It rev
165: Specific revision.
166: .It rev1:rev2
167: Delete all revisions of a branch between
168: .Ar rev1
169: and
170: .Ar rev2 .
171: .It rev1::rev2
172: Delete all revisions of a branch between
173: .Ar rev1
174: and
175: .Ar rev2
176: without deleting revisions
177: .Ar rev1
178: and
179: .Ar rev2 .
180: .It :rev
181: Delete all revisions of the branch until revision
182: .Ar rev .
183: .It rev:
184: Delete all revisions of the branch from revision
185: .Ar rev
186: until the last revision of the branch.
187: .El
1.13 xsa 188: .It Fl q
189: Be quiet about reporting.
1.14 xsa 190: .Sm off
1.20 xsa 191: .It Fl s Ar state Op : Ar rev
192: .Sm on
193: Sets the state of revision
194: .Ar rev
195: to the identifier
196: .Ar state .
197: The specified value may not contain a space character.
1.16 xsa 198: .It Fl T
1.17 jmc 199: Preserve the modification time of RCS files.
1.20 xsa 200: .Sm off
1.14 xsa 201: .It Fl t Ar file \*(Ba Ar str
202: .Sm on
203: Change the descriptive text.
204: The descriptive text is taken from the
205: .Ar file
206: specified as argument or from the string
207: .Ar str
208: given as argument if it is preceded by the
209: .Sq -
210: character.
211: If no argument is used, the descriptive text is taken from standard input
212: terminated by end-of-file or by a line containing the
213: .Sq \&.
214: character by itself.
1.1 deraadt 215: .It Fl U
216: Disable strict locking on the RCS files.
1.24 ray 217: .It Fl u Ns Op Ar rev
218: Unlock revision
219: .Ar rev
220: on the RCS files.
1.1 deraadt 221: .It Fl V
222: Print the program's version string and exit.
1.15 xsa 223: .It Fl x Ns Ar suffixes
224: Specifies the suffixes for RCS files.
225: Suffixes should be separated by the
226: .Sq /
227: character.
1.25 jmc 228: .El
229: .Sh KEYWORD SUBSTITUTION
1.40 jmc 230: As long as source files are edited inside a working directory,
231: their state can be determined using the
1.27 jmc 232: .Xr cvs 1
1.25 jmc 233: .Ic status
234: or
235: .Ic log
236: commands, but as soon as files get exported from
1.40 jmc 237: a local working copy, it becomes harder to identify which
1.25 jmc 238: revisions they are.
239: .Pp
240: .Nm
241: and
242: .Xr cvs 1
1.40 jmc 243: use a mechanism known as
1.25 jmc 244: .Sq keyword substitution
245: to help identify the files.
246: Embedded strings of the form $keyword$ and $keyword:...$ in a file
1.40 jmc 247: are replaced with strings of the form $keyword: value$ whenever
248: a new revision of the file is obtained.
1.25 jmc 249: The possible keywords are as follows:
1.30 jmc 250: .Bl -tag -width "XrevisionXX" -offset "XXX"
1.25 jmc 251: .It $\&Author$
252: The name of the user who checked in the revision.
253: .It $\&Date$
254: The date and hour (UTC) the revision was checked in.
255: .It $\&Header$
256: Standard header containing the full pathname of the RCS
257: file, the revision number, the date (UTC), the author and the state.
258: .It $\&Id$
259: The same content as $\&Header$ but without the path
260: of the RCS file.
261: .It $\&Log$
262: The log message supplied during commit, preceded by a header
263: containing the RCS filename, the revision number, the
264: author, and the date (UTC).
265: .It $\&Name$
266: The tag name used to check out the file.
267: .It $\&RCSfile$
268: The name of the RCS file, but without a path.
269: .It $\&Revision$
270: The revision number assigned to the revision.
271: .It $\&Source$
272: The full pathname of the RCS file.
273: .It $\&State$
274: The state assigned to the revision.
275: .El
276: .Pp
277: Keyword substitution has its disadvantages: sometimes the
278: literal text string $\&Author$ is wanted inside a file without
279: .Nm
1.27 jmc 280: or
281: .Xr cvs 1
1.25 jmc 282: interpreting it as a keyword and expanding it into something like
283: $\&Author$.
284: The
1.26 jmc 285: .Fl k Ns Ar o
1.25 jmc 286: option can be used to turn off keyword substitution entirely though.
287: There is unfortunately no way to selectively turn off keyword substitution.
288: .Pp
289: Each file and working directory copy of a file have a stored
290: default substitution mode.
291: Substitution modes on files are set by the
292: .Fl k Ns Ar mode
293: option.
294: .Pp
295: The possible substitution modes are as follows:
296: .Bl -tag -width Ds -offset 3n
1.26 jmc 297: .It Fl k Ns Ar b
1.25 jmc 298: Like
1.26 jmc 299: .Fl k Ns Ar o ,
1.25 jmc 300: but also avoids the conversion of line endings.
301: This option is used to handle binary files.
1.26 jmc 302: .It Fl k Ns Ar k
1.25 jmc 303: Does not substitute the keywords.
304: Useful with the
1.27 jmc 305: .Xr cvs 1
1.25 jmc 306: .Ic diff
1.28 jmc 307: and
308: .Xr rcsdiff 1
309: commands to avoid displaying the differences between keyword substitutions.
1.26 jmc 310: .It Fl k Ns Ar kv
1.25 jmc 311: The default behaviour.
312: Keywords are normally substituted i.e. $\&Revision$ becomes
313: $\&Revision: 1.1 $.
1.26 jmc 314: .It Fl k Ns Ar kvl
1.25 jmc 315: Like
1.26 jmc 316: .Fl k Ns Ar kv ,
1.25 jmc 317: except that the locker's name is displayed along with the version
318: if the given revision is currently locked.
319: This option is normally not useful as
320: .Nm
1.27 jmc 321: and
322: .Xr cvs 1
323: do not use file locking by default.
1.26 jmc 324: .It Fl k Ns Ar o
1.25 jmc 325: No substitutions are done.
326: This option is often used with the
1.27 jmc 327: .Xr cvs 1
1.25 jmc 328: .Ic import
329: command to guarantee that files that already contain external keywords
330: do not get modified.
1.26 jmc 331: .It Fl k Ns Ar v
1.25 jmc 332: Substitute the value of keywords instead of keywords themselves
333: e.g. instead of $\&Revision$, only insert 1.1 and not $\&Revision: 1.1 $.
334: This option must be used with care, as it can only be used once.
335: It is often used with the
1.27 jmc 336: .Xr cvs 1
1.25 jmc 337: .Ic export
338: command to freeze the values before releasing software.
1.1 deraadt 339: .El
340: .Sh ENVIRONMENT
341: .Bl -tag -width RCSINIT
342: .It Ev RCSINIT
343: If set, this variable should contain a list of space-delimited options that
344: are prepended to the argument list.
345: .El
1.22 jmc 346: .Sh EXAMPLES
347: One of the most common uses of
348: .Nm
349: is to track changes to a document containing source code.
350: .Pp
351: As an example,
352: we'll look at a user wishing to track source changes to a file
353: .Ar foo.c .
354: .Pp
355: If the
356: .Ar RCS
357: directory does not exist yet, create it as follows and invoke the
358: check-in command:
359: .Bd -literal -offset indent
360: $ mkdir RCS
361: $ ci foo.c
362: .Ed
363: .Pp
364: This command creates an RCS file
365: .Ar foo.c,v
366: in the
367: .Ar RCS
368: directory, stores
369: .Ar foo.c
370: into it as revision 1.1, and deletes
371: .Ar foo.c .
372: .Xr ci 1
373: will prompt for a description of the file to be entered.
374: Whenever a newly created (or updated) file is checked-in,
375: .Xr ci 1
376: will prompt for a log message to be entered which should summarize
377: the changes made to the file.
378: That log message will be added to the RCS file along with the new revision.
379: .Pp
380: The
381: .Xr co 1
382: command can now be used to obtain a copy of the checked-in
383: .Ar foo.c,v
384: file:
385: .Pp
386: .Dl $ co foo.c
387: .Pp
1.36 jmc 388: This command checks the file out in unlocked mode.
1.22 jmc 389: If a user wants to have exclusive access to the file to make changes to it,
390: it needs to be checked out in locked mode using the
391: .Fl l
392: option of the
393: .Xr co 1
394: command.
395: Only one concurrent locked checkout of a revision is permitted.
396: .Pp
397: Once changes have been made to the
398: .Pa foo.c
399: file, and before checking the file in, the
400: .Xr rcsdiff 1
401: command can be used to view changes between the working file
402: and the most recently checked-in revision:
403: .Pp
404: .Dl $ rcsdiff -u foo.c
405: .Pp
406: The
407: .Fl u
408: option produces a unified diff.
409: See
410: .Xr diff 1
411: for more information.
1.1 deraadt 412: .Sh SEE ALSO
413: .Xr ci 1 ,
414: .Xr co 1 ,
1.3 jmc 415: .Xr ident 1 ,
1.1 deraadt 416: .Xr rcsclean 1 ,
417: .Xr rcsdiff 1 ,
1.8 xsa 418: .Xr rcsmerge 1 ,
1.6 xsa 419: .Xr rlog 1
1.21 jmc 420: .Sh STANDARDS
1.31 jmc 421: OpenRCS is compatible with
422: Walter Tichy's original RCS implementation.
423: .Pp
1.37 jmc 424: The flags
425: .Op Fl Mz
426: have no effect and are provided
1.21 jmc 427: for compatibility only.
1.32 jmc 428: .Sh HISTORY
429: The OpenRCS project is a BSD-licensed rewrite of the original
430: Revision Control System.
431: OpenRCS is written by Jean-Francois Brousseau, Joris Vink,
432: Niall O'Higgins, and Xavier Santolaria.
1.35 jmc 433: .Pp
1.32 jmc 434: The original RCS code was written in large parts by Walter F. Tichy
435: and Paul Eggert.
1.29 jmc 436: .Sh CAVEATS
437: For historical reasons,
438: the RCS tools do not permit whitespace between options and their arguments.
![[BACK]](/icons/back.gif){kind=icon}
Return to rcs.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / rcs