Annotation of src/usr.bin/rcs/rcs.1, Revision 1.22
1.22 ! jmc 1: .\" $OpenBSD: rcs.1,v 1.21 2006/03/06 14:37:23 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.20 xsa 42: .Oo Fl m Ns Ar rev Ns :
43: .Ar msg Oc
1.19 xsa 44: .Op Fl o Ns Ar rev
1.20 xsa 45: .Oo Fl s Ns Ar state Ns
46: .Op : Ns Ar rev Oc
1.14 xsa 47: .Oo Fl t Ns Ar file Ns \*(Ba
48: .Ar str Oc
1.15 xsa 49: .Op Fl x Ns Ar suffixes
1.14 xsa 50: .Ar file ...
1.1 deraadt 51: .Sh DESCRIPTION
1.22 ! jmc 52: Revision Control System (RCS) is a software tool which lets people
! 53: manage multiple revisions of text that is revised frequently, such as
! 54: source code or documentation.
! 55: .Pp
1.1 deraadt 56: The
57: .Nm
58: program is used to create RCS files or manipulate the contents of existing
59: files.
1.22 ! jmc 60: A set of helper tools is also available:
! 61: specific revisions of files may be checked in or out, using
! 62: .Xr ci 1
! 63: and
! 64: .Xr co 1 ;
! 65: differences between revisions viewed or merged, using
! 66: .Xr rcsdiff 1
! 67: and
! 68: .Xr rcsmerge 1 ;
! 69: and information about RCS files and keyword strings displayed using
! 70: .Xr rlog 1
! 71: and
! 72: .Xr ident 1 .
! 73: See the respective manual pages for more information
! 74: about these utilities.
1.1 deraadt 75: .Pp
76: The following options are supported:
77: .Bl -tag -width "-e usersXX"
1.14 xsa 78: .It Fl A Ns Ar oldfile
79: Append the access list of
80: .Ar oldfile
81: to the access list of the RCS files.
1.7 niallo 82: .It Fl a Ns Ar users
1.1 deraadt 83: Add the usernames specified in the comma-separated list
84: .Ar users
85: to the access list of the RCS files.
1.7 niallo 86: .It Fl b Ns Op Ar rev
1.14 xsa 87: Set the default branch to
88: .Ar rev .
1.12 xsa 89: .It Fl c Ns Ar string
90: Set comment leader to
91: .Ar string .
1.7 niallo 92: .It Fl e Ns Op Ar users
1.1 deraadt 93: Remove the usernames specified in the comma-separated list
94: .Ar users
95: from the access list of the RCS files.
96: If
97: .Ar users
98: is not specified, all users are removed from the access list.
99: .It Fl h
100: Display the program's usage and exit.
1.20 xsa 101: .It Fl I
102: Interactive mode.
1.1 deraadt 103: .It Fl i
1.10 xsa 104: Create and initialize a new RCS file.
1.11 jmc 105: If the RCS file has no path prefix, try to first create it in the
1.10 xsa 106: .Pa ./RCS
1.11 jmc 107: subdirectory or, if that fails, in the current directory.
1.1 deraadt 108: Files created this way contain no revision.
1.9 xsa 109: .It Fl k Ns Ar mode
110: Specify the keyword substitution mode.
1.1 deraadt 111: .It Fl L
112: Enable strict locking on the RCS files.
113: See
114: .Xr rcsfile 5
115: for more details on locking.
116: .It Fl M
117: Disable mail warnings when breaking a user's lock.
118: Normally,
119: .Nm
120: will send a mail to the lock owner when his lock is removed by a call
121: to
122: .Nm
123: .Fl u .
124: This option is currently ignored.
1.7 niallo 125: .It Fl m Ns Ar rev : Ns Ar msg
1.5 jmc 126: Replace revision
127: .Ar rev Ns 's
128: log message with
129: .Ar msg .
1.19 xsa 130: .It Fl o Ns Ar rev
131: Delete one or more revisions.
132: The specifications of the values or revisions are as follows:
133: .Bl -tag -width Ds
134: .It rev
135: Specific revision.
136: .It rev1:rev2
137: Delete all revisions of a branch between
138: .Ar rev1
139: and
140: .Ar rev2 .
141: .It rev1::rev2
142: Delete all revisions of a branch between
143: .Ar rev1
144: and
145: .Ar rev2
146: without deleting revisions
147: .Ar rev1
148: and
149: .Ar rev2 .
150: .It :rev
151: Delete all revisions of the branch until revision
152: .Ar rev .
153: .It rev:
154: Delete all revisions of the branch from revision
155: .Ar rev
156: until the last revision of the branch.
157: .El
1.13 xsa 158: .It Fl q
159: Be quiet about reporting.
1.14 xsa 160: .Sm off
1.20 xsa 161: .It Fl s Ar state Op : Ar rev
162: .Sm on
163: Sets the state of revision
164: .Ar rev
165: to the identifier
166: .Ar state .
167: The specified value may not contain a space character.
168: If
169: .Ar rev
170: is not specified, the latest revision of the default branch
171: is assumed.
1.16 xsa 172: .It Fl T
1.17 jmc 173: Preserve the modification time of RCS files.
1.20 xsa 174: .Sm off
1.14 xsa 175: .It Fl t Ar file \*(Ba Ar str
176: .Sm on
177: Change the descriptive text.
178: The descriptive text is taken from the
179: .Ar file
180: specified as argument or from the string
181: .Ar str
182: given as argument if it is preceded by the
183: .Sq -
184: character.
185: If no argument is used, the descriptive text is taken from standard input
186: terminated by end-of-file or by a line containing the
187: .Sq \&.
188: character by itself.
1.1 deraadt 189: .It Fl U
190: Disable strict locking on the RCS files.
191: See
192: .Xr rcsfile 5
193: for more details on locking.
194: .It Fl V
195: Print the program's version string and exit.
1.15 xsa 196: .It Fl x Ns Ar suffixes
197: Specifies the suffixes for RCS files.
198: Suffixes should be separated by the
199: .Sq /
200: character.
1.1 deraadt 201: .El
202: .Sh ENVIRONMENT
203: .Bl -tag -width RCSINIT
204: .It Ev RCSINIT
205: If set, this variable should contain a list of space-delimited options that
206: are prepended to the argument list.
207: .El
1.22 ! jmc 208: .Sh EXAMPLES
! 209: One of the most common uses of
! 210: .Nm
! 211: is to track changes to a document containing source code.
! 212: .Pp
! 213: As an example,
! 214: we'll look at a user wishing to track source changes to a file
! 215: .Ar foo.c .
! 216: .Pp
! 217: If the
! 218: .Ar RCS
! 219: directory does not exist yet, create it as follows and invoke the
! 220: check-in command:
! 221: .Bd -literal -offset indent
! 222: $ mkdir RCS
! 223: $ ci foo.c
! 224: .Ed
! 225: .Pp
! 226: This command creates an RCS file
! 227: .Ar foo.c,v
! 228: in the
! 229: .Ar RCS
! 230: directory, stores
! 231: .Ar foo.c
! 232: into it as revision 1.1, and deletes
! 233: .Ar foo.c .
! 234: .Xr ci 1
! 235: will prompt for a description of the file to be entered.
! 236: Whenever a newly created (or updated) file is checked-in,
! 237: .Xr ci 1
! 238: will prompt for a log message to be entered which should summarize
! 239: the changes made to the file.
! 240: That log message will be added to the RCS file along with the new revision.
! 241: .Pp
! 242: The
! 243: .Xr co 1
! 244: command can now be used to obtain a copy of the checked-in
! 245: .Ar foo.c,v
! 246: file:
! 247: .Pp
! 248: .Dl $ co foo.c
! 249: .Pp
! 250: This command checks the file out in shared or unlocked mode.
! 251: If a user wants to have exclusive access to the file to make changes to it,
! 252: it needs to be checked out in locked mode using the
! 253: .Fl l
! 254: option of the
! 255: .Xr co 1
! 256: command.
! 257: Only one concurrent locked checkout of a revision is permitted.
! 258: .Pp
! 259: Once changes have been made to the
! 260: .Pa foo.c
! 261: file, and before checking the file in, the
! 262: .Xr rcsdiff 1
! 263: command can be used to view changes between the working file
! 264: and the most recently checked-in revision:
! 265: .Pp
! 266: .Dl $ rcsdiff -u foo.c
! 267: .Pp
! 268: The
! 269: .Fl u
! 270: option produces a unified diff.
! 271: See
! 272: .Xr diff 1
! 273: for more information.
1.1 deraadt 274: .Sh SEE ALSO
275: .Xr ci 1 ,
276: .Xr co 1 ,
1.3 jmc 277: .Xr ident 1 ,
1.1 deraadt 278: .Xr rcsclean 1 ,
279: .Xr rcsdiff 1 ,
1.8 xsa 280: .Xr rcsmerge 1 ,
1.6 xsa 281: .Xr rlog 1
1.21 jmc 282: .Sh STANDARDS
283: The flag
284: .Op Fl z
285: has no effect and is provided
286: for compatibility only.