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