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