Annotation of src/usr.bin/rcs/rcs.1, Revision 1.27
1.27 ! jmc 1: .\" $OpenBSD: rcs.1,v 1.26 2006/04/19 12:44:00 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.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
1.27 ! jmc 222: .Xr cvs 1
1.25 jmc 223: .Ic status
224: or
225: .Ic log
226: commands, but as soon as files get exported from
227: your local working copy, it becomes harder to identify which
228: revisions they are.
229: .Pp
230: .Nm
231: and
232: .Xr cvs 1
233: can use a mechanism known as
234: .Sq keyword substitution
235: to help identify the files.
236: Embedded strings of the form $keyword$ and $keyword:...$ in a file
237: are replaced with strings of the form $keyword: value$ whenever you
238: obtain a new revision of the file.
239: The possible keywords are as follows:
240: .Bl -tag -width Ds
241: .It $\&Author$
242: The name of the user who checked in the revision.
243: .It $\&Date$
244: The date and hour (UTC) the revision was checked in.
245: .It $\&Header$
246: Standard header containing the full pathname of the RCS
247: file, the revision number, the date (UTC), the author and the state.
248: .It $\&Id$
249: The same content as $\&Header$ but without the path
250: of the RCS file.
251: .It $\&Log$
252: The log message supplied during commit, preceded by a header
253: containing the RCS filename, the revision number, the
254: author, and the date (UTC).
255: .It $\&Name$
256: The tag name used to check out the file.
257: .It $\&RCSfile$
258: The name of the RCS file, but without a path.
259: .It $\&Revision$
260: The revision number assigned to the revision.
261: .It $\&Source$
262: The full pathname of the RCS file.
263: .It $\&State$
264: The state assigned to the revision.
265: .El
266: .Pp
267: Keyword substitution has its disadvantages: sometimes the
268: literal text string $\&Author$ is wanted inside a file without
269: .Nm
1.27 ! jmc 270: or
! 271: .Xr cvs 1
1.25 jmc 272: interpreting it as a keyword and expanding it into something like
273: $\&Author$.
274: The
1.26 jmc 275: .Fl k Ns Ar o
1.25 jmc 276: option can be used to turn off keyword substitution entirely though.
277: There is unfortunately no way to selectively turn off keyword substitution.
278: .Pp
279: Each file and working directory copy of a file have a stored
280: default substitution mode.
281: Substitution modes on files are set by the
282: .Fl k Ns Ar mode
283: option.
284: .Pp
285: The possible substitution modes are as follows:
286: .Bl -tag -width Ds -offset 3n
1.26 jmc 287: .It Fl k Ns Ar b
1.25 jmc 288: Like
1.26 jmc 289: .Fl k Ns Ar o ,
1.25 jmc 290: but also avoids the conversion of line endings.
291: This option is used to handle binary files.
1.26 jmc 292: .It Fl k Ns Ar k
1.25 jmc 293: Does not substitute the keywords.
294: Useful with the
1.27 ! jmc 295: .Xr cvs 1
1.25 jmc 296: .Ic diff
297: command 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
376: This command checks the file out in shared or unlocked mode.
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
409: The flag
410: .Op Fl z
411: has no effect and is provided
412: 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