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