Annotation of src/usr.bin/rcs/rcs.1, Revision 1.60
1.60 ! schwarze 1: .\" $OpenBSD: rcs.1,v 1.59 2015/09/25 15:31:24 schwarze 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: .\"
1.60 ! schwarze 27: .Dd $Mdocdate: September 25 2015 $
1.1 deraadt 28: .Dt RCS 1
29: .Os
30: .Sh NAME
31: .Nm rcs
32: .Nd RCS file management program
33: .Sh SYNOPSIS
34: .Nm
1.47 niallo 35: .Op Fl IiLqTUV
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.59 schwarze 43: .Op Fl m Ns Ar rev : Ns Ar msg
1.19 xsa 44: .Op Fl o Ns Ar rev
1.56 sobrado 45: .Op Fl t Ns Op Ar str
1.24 ray 46: .Op Fl u Ns Op Ar rev
1.15 xsa 47: .Op Fl x Ns Ar suffixes
1.30 jmc 48: .Ar
1.1 deraadt 49: .Sh DESCRIPTION
1.22 jmc 50: Revision Control System (RCS) is a software tool which lets people
51: manage multiple revisions of text that is revised frequently, such as
52: source code or documentation.
53: .Pp
1.1 deraadt 54: The
55: .Nm
56: program is used to create RCS files or manipulate the contents of existing
57: files.
1.22 jmc 58: A set of helper tools is also available:
59: specific revisions of files may be checked in or out, using
60: .Xr ci 1
61: and
62: .Xr co 1 ;
63: differences between revisions viewed or merged, using
64: .Xr rcsdiff 1
65: and
66: .Xr rcsmerge 1 ;
67: and information about RCS files and keyword strings displayed using
68: .Xr rlog 1
69: and
70: .Xr ident 1 .
71: See the respective manual pages for more information
72: about these utilities.
1.1 deraadt 73: .Pp
74: The following options are supported:
75: .Bl -tag -width "-e usersXX"
1.14 xsa 76: .It Fl A Ns Ar oldfile
77: Append the access list of
78: .Ar oldfile
79: to the access list of the RCS files.
1.7 niallo 80: .It Fl a Ns Ar users
1.1 deraadt 81: Add the usernames specified in the comma-separated list
82: .Ar users
83: to the access list of the RCS files.
1.7 niallo 84: .It Fl b Ns Op Ar rev
1.45 jmc 85: Set the default branch (see below) to
1.14 xsa 86: .Ar rev .
1.45 jmc 87: If no argument is specified,
88: the default branch is set to the highest numbered branch.
1.12 xsa 89: .It Fl c Ns Ar string
90: Set comment leader to
91: .Ar string .
1.41 jmc 92: The comment leader specifies the comment character(s) for a file.
93: This option is useful for compatibility with older RCS implementations
94: only.
1.7 niallo 95: .It Fl e Ns Op Ar users
1.1 deraadt 96: Remove the usernames specified in the comma-separated list
97: .Ar users
98: from the access list of the RCS files.
99: If
100: .Ar users
101: is not specified, all users are removed from the access list.
1.20 xsa 102: .It Fl I
103: Interactive mode.
1.1 deraadt 104: .It Fl i
1.10 xsa 105: Create and initialize a new RCS file.
1.11 jmc 106: If the RCS file has no path prefix, try to first create it in the
1.10 xsa 107: .Pa ./RCS
1.11 jmc 108: subdirectory or, if that fails, in the current directory.
1.1 deraadt 109: Files created this way contain no revision.
1.9 xsa 110: .It Fl k Ns Ar mode
1.44 jmc 111: Specify the keyword substitution mode (see below).
1.1 deraadt 112: .It Fl L
113: Enable strict locking on the RCS files.
1.24 ray 114: .It Fl l Ns Op Ar rev
115: Lock revision
116: .Ar rev
117: on the RCS files.
1.7 niallo 118: .It Fl m Ns Ar rev : Ns Ar msg
1.5 jmc 119: Replace revision
120: .Ar rev Ns 's
121: log message with
122: .Ar msg .
1.19 xsa 123: .It Fl o Ns Ar rev
124: Delete one or more revisions.
125: The specifications of the values or revisions are as follows:
126: .Bl -tag -width Ds
127: .It rev
128: Specific revision.
129: .It rev1:rev2
130: Delete all revisions of a branch between
131: .Ar rev1
132: and
133: .Ar rev2 .
134: .It rev1::rev2
135: Delete all revisions of a branch between
136: .Ar rev1
137: and
138: .Ar rev2
139: without deleting revisions
140: .Ar rev1
141: and
142: .Ar rev2 .
143: .It :rev
144: Delete all revisions of the branch until revision
145: .Ar rev .
146: .It rev:
147: Delete all revisions of the branch from revision
148: .Ar rev
149: until the last revision of the branch.
150: .El
1.13 xsa 151: .It Fl q
152: Be quiet about reporting.
1.16 xsa 153: .It Fl T
1.17 jmc 154: Preserve the modification time of RCS files.
1.56 sobrado 155: .It Fl t Ns Op Ar str
1.14 xsa 156: Change the descriptive text.
1.43 ray 157: The argument
1.14 xsa 158: .Ar str
1.43 ray 159: is interpreted as the name of a file containing
160: the descriptive text or,
161: if prefixed with a
162: .Sq - ,
163: the actual descriptive text itself.
1.14 xsa 164: If no argument is used, the descriptive text is taken from standard input
165: terminated by end-of-file or by a line containing the
166: .Sq \&.
167: character by itself.
1.1 deraadt 168: .It Fl U
169: Disable strict locking on the RCS files.
1.24 ray 170: .It Fl u Ns Op Ar rev
171: Unlock revision
172: .Ar rev
173: on the RCS files.
1.1 deraadt 174: .It Fl V
175: Print the program's version string and exit.
1.15 xsa 176: .It Fl x Ns Ar suffixes
177: Specifies the suffixes for RCS files.
178: Suffixes should be separated by the
179: .Sq /
180: character.
1.25 jmc 181: .El
1.44 jmc 182: .Sh BRANCHES AND REVISIONS
183: Files may be selected by
184: .Em revision
185: or, where no revision is specified,
186: the latest revision of the default
187: .Em branch
188: is used.
189: Revisions are specified either by using the
190: .Fl r
191: option or
192: by appending the revision number to any option that supports it.
193: Branches are selected using the
194: .Fl b
195: option.
196: .Pp
197: A file's revision consists of two elements:
198: release number and level number.
199: For example, revision 2.3 of a file denotes release 2, level 3.
200: Levels may also be subdivided into sublevels:
201: this might happen, for example,
202: if a parallel development is forked from a lower level revision.
203: The primary levels and the sublevels belong to separate branches:
204: the primary levels belong to a branch called HEAD,
205: while sublevels belong to branches specified by revision.
206: .Pp
207: .Nm
208: also supports the notion of
209: .Em state .
210: The state is an arbitrary string of characters used to describe a file
211: (or a specific revision of a file).
212: States can be set or changed using the
213: .Fl s
214: option, for RCS tools which support it.
215: The state of a file/revision can be modified without having to check in
216: a new file/revision.
217: The default state is
218: .Sq Exp
219: (Experimental).
220: Examples of states could be
221: .Sq Dev ,
222: .Sq Reviewed ,
223: or
224: .Sq Stab .
225: .Pp
226: In order to make large groups of RCS files more manageable,
227: RCS tools have the ability to select files by their
228: .Em symbolic name .
229: Thus files can be selected by their symbolic name,
230: rather than numerical revision.
231: .Xr ci 1
232: .Fl N
233: and
234: .Fl n
235: are used to set symbolic names for files.
236: .Pp
237: The following methods of file selection are therefore available:
238: revision number, state, and symbolic name.
239: For options which take as argument
240: .Ar rev
241: or
242: .Ar state ,
243: any of these methods may be used.
244: Some examples:
245: .Bd -literal -offset indent
246: $ co -r"myproject" foo.c
247: $ rcs -m1.3:update foo.c
248: $ ci -s"Exp" bar.c
249: .Ed
1.25 jmc 250: .Sh KEYWORD SUBSTITUTION
1.40 jmc 251: As long as source files are edited inside a working directory,
252: their state can be determined using the
1.27 jmc 253: .Xr cvs 1
1.25 jmc 254: .Ic status
255: or
256: .Ic log
257: commands, but as soon as files get exported from
1.40 jmc 258: a local working copy, it becomes harder to identify which
1.25 jmc 259: revisions they are.
260: .Pp
261: .Nm
262: and
263: .Xr cvs 1
1.40 jmc 264: use a mechanism known as
1.25 jmc 265: .Sq keyword substitution
266: to help identify the files.
267: Embedded strings of the form $keyword$ and $keyword:...$ in a file
1.40 jmc 268: are replaced with strings of the form $keyword: value$ whenever
269: a new revision of the file is obtained.
1.25 jmc 270: The possible keywords are as follows:
1.30 jmc 271: .Bl -tag -width "XrevisionXX" -offset "XXX"
1.25 jmc 272: .It $\&Author$
273: The name of the user who checked in the revision.
274: .It $\&Date$
275: The date and hour (UTC) the revision was checked in.
276: .It $\&Header$
277: Standard header containing the full pathname of the RCS
278: file, the revision number, the date (UTC), the author and the state.
1.58 guenther 279: .It $\&Id$ and $\&OpenBSD$
1.25 jmc 280: The same content as $\&Header$ but without the path
281: of the RCS file.
282: .It $\&Log$
283: The log message supplied during commit, preceded by a header
284: containing the RCS filename, the revision number, the
285: author, and the date (UTC).
1.54 jmc 286: .It $\&Mdocdate$
1.52 jmc 287: Produce a date of the form month name, day number, and year,
288: suitable for the
289: .Xr mdoc 7
290: .Dq \&Dd
291: macro.
1.25 jmc 292: .It $\&Name$
293: The tag name used to check out the file.
294: .It $\&RCSfile$
295: The name of the RCS file, but without a path.
296: .It $\&Revision$
297: The revision number assigned to the revision.
298: .It $\&Source$
299: The full pathname of the RCS file.
300: .It $\&State$
301: The state assigned to the revision.
302: .El
303: .Pp
304: Keyword substitution has its disadvantages: sometimes the
305: literal text string $\&Author$ is wanted inside a file without
306: .Nm
1.27 jmc 307: or
308: .Xr cvs 1
1.51 jmc 309: interpreting it as a keyword and expanding it.
1.25 jmc 310: The
1.26 jmc 311: .Fl k Ns Ar o
1.25 jmc 312: option can be used to turn off keyword substitution entirely though.
313: There is unfortunately no way to selectively turn off keyword substitution.
314: .Pp
315: Each file and working directory copy of a file have a stored
316: default substitution mode.
317: Substitution modes on files are set by the
318: .Fl k Ns Ar mode
319: option.
320: .Pp
321: The possible substitution modes are as follows:
322: .Bl -tag -width Ds -offset 3n
1.26 jmc 323: .It Fl k Ns Ar b
1.25 jmc 324: Like
1.26 jmc 325: .Fl k Ns Ar o ,
1.25 jmc 326: but also avoids the conversion of line endings.
327: This option is used to handle binary files.
1.26 jmc 328: .It Fl k Ns Ar k
1.25 jmc 329: Does not substitute the keywords.
330: Useful with the
1.27 jmc 331: .Xr cvs 1
1.25 jmc 332: .Ic diff
1.28 jmc 333: and
334: .Xr rcsdiff 1
335: commands to avoid displaying the differences between keyword substitutions.
1.26 jmc 336: .It Fl k Ns Ar kv
1.25 jmc 337: The default behaviour.
338: Keywords are normally substituted i.e. $\&Revision$ becomes
339: $\&Revision: 1.1 $.
1.26 jmc 340: .It Fl k Ns Ar kvl
1.25 jmc 341: Like
1.26 jmc 342: .Fl k Ns Ar kv ,
1.25 jmc 343: except that the locker's name is displayed along with the version
344: if the given revision is currently locked.
345: This option is normally not useful as
346: .Nm
1.27 jmc 347: and
348: .Xr cvs 1
349: do not use file locking by default.
1.26 jmc 350: .It Fl k Ns Ar o
1.25 jmc 351: No substitutions are done.
352: This option is often used with the
1.27 jmc 353: .Xr cvs 1
1.25 jmc 354: .Ic import
355: command to guarantee that files that already contain external keywords
356: do not get modified.
1.26 jmc 357: .It Fl k Ns Ar v
1.25 jmc 358: Substitute the value of keywords instead of keywords themselves
359: e.g. instead of $\&Revision$, only insert 1.1 and not $\&Revision: 1.1 $.
360: This option must be used with care, as it can only be used once.
361: It is often used with the
1.27 jmc 362: .Xr cvs 1
1.25 jmc 363: .Ic export
364: command to freeze the values before releasing software.
1.1 deraadt 365: .El
366: .Sh ENVIRONMENT
367: .Bl -tag -width RCSINIT
368: .It Ev RCSINIT
369: If set, this variable should contain a list of space-delimited options that
370: are prepended to the argument list.
371: .El
1.55 jmc 372: .Sh EXIT STATUS
373: .Ex -std rcs
1.22 jmc 374: .Sh EXAMPLES
375: One of the most common uses of
376: .Nm
377: is to track changes to a document containing source code.
378: .Pp
379: As an example,
380: we'll look at a user wishing to track source changes to a file
381: .Ar foo.c .
382: .Pp
383: If the
384: .Ar RCS
385: directory does not exist yet, create it as follows and invoke the
386: check-in command:
387: .Bd -literal -offset indent
388: $ mkdir RCS
389: $ ci foo.c
390: .Ed
391: .Pp
392: This command creates an RCS file
393: .Ar foo.c,v
394: in the
395: .Ar RCS
396: directory, stores
397: .Ar foo.c
398: into it as revision 1.1, and deletes
399: .Ar foo.c .
400: .Xr ci 1
401: will prompt for a description of the file to be entered.
402: Whenever a newly created (or updated) file is checked-in,
403: .Xr ci 1
404: will prompt for a log message to be entered which should summarize
405: the changes made to the file.
406: That log message will be added to the RCS file along with the new revision.
407: .Pp
408: The
409: .Xr co 1
410: command can now be used to obtain a copy of the checked-in
411: .Ar foo.c,v
412: file:
413: .Pp
414: .Dl $ co foo.c
415: .Pp
1.36 jmc 416: This command checks the file out in unlocked mode.
1.22 jmc 417: If a user wants to have exclusive access to the file to make changes to it,
418: it needs to be checked out in locked mode using the
419: .Fl l
420: option of the
421: .Xr co 1
422: command.
423: Only one concurrent locked checkout of a revision is permitted.
424: .Pp
425: Once changes have been made to the
426: .Pa foo.c
427: file, and before checking the file in, the
428: .Xr rcsdiff 1
429: command can be used to view changes between the working file
430: and the most recently checked-in revision:
431: .Pp
432: .Dl $ rcsdiff -u foo.c
433: .Pp
434: The
435: .Fl u
436: option produces a unified diff.
437: See
438: .Xr diff 1
439: for more information.
1.1 deraadt 440: .Sh SEE ALSO
441: .Xr ci 1 ,
442: .Xr co 1 ,
1.57 jmc 443: .Xr cvs 1 ,
1.3 jmc 444: .Xr ident 1 ,
1.1 deraadt 445: .Xr rcsclean 1 ,
446: .Xr rcsdiff 1 ,
1.8 xsa 447: .Xr rcsmerge 1 ,
1.6 xsa 448: .Xr rlog 1
1.50 jsg 449: .Rs
450: .%A Tichy, Walter F.
451: .%T "RCS -- a system for version control"
452: .%J "Software--Practice & Experience"
453: .%V 15:7
454: .%D July, 1985
455: .%P pp. 637-654
456: .Re
1.21 jmc 457: .Sh STANDARDS
1.31 jmc 458: OpenRCS is compatible with
459: Walter Tichy's original RCS implementation.
460: .Pp
1.37 jmc 461: The flags
462: .Op Fl Mz
463: have no effect and are provided
1.21 jmc 464: for compatibility only.
1.32 jmc 465: .Sh HISTORY
466: The OpenRCS project is a BSD-licensed rewrite of the original
1.60 ! schwarze 467: Revision Control System and first appeared in
! 468: .Ox 4.0 .
! 469: .Sh AUTHORS
! 470: .An -nosplit
! 471: OpenRCS was written by
! 472: .An Jean-Francois Brousseau ,
! 473: .An Joris Vink ,
! 474: .An Niall O'Higgins ,
! 475: and
! 476: .An Xavier Santolaria .
1.35 jmc 477: .Pp
1.60 ! schwarze 478: The original RCS code was written in large parts by
! 479: .An Walter F. Tichy
! 480: and
! 481: .An Paul Eggert .
1.29 jmc 482: .Sh CAVEATS
483: For historical reasons,
484: 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