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