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