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