1.\" $OpenBSD: rcs.1,v 1.58 2013/01/18 11:21:09 guenther 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: January 18 2013 $ 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 Op 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 Op 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.Sh BRANCHES AND REVISIONS 184Files may be selected by 185.Em revision 186or, where no revision is specified, 187the latest revision of the default 188.Em branch 189is used. 190Revisions are specified either by using the 191.Fl r 192option or 193by appending the revision number to any option that supports it. 194Branches are selected using the 195.Fl b 196option. 197.Pp 198A file's revision consists of two elements: 199release number and level number. 200For example, revision 2.3 of a file denotes release 2, level 3. 201Levels may also be subdivided into sublevels: 202this might happen, for example, 203if a parallel development is forked from a lower level revision. 204The primary levels and the sublevels belong to separate branches: 205the primary levels belong to a branch called HEAD, 206while sublevels belong to branches specified by revision. 207.Pp 208.Nm 209also supports the notion of 210.Em state . 211The state is an arbitrary string of characters used to describe a file 212(or a specific revision of a file). 213States can be set or changed using the 214.Fl s 215option, for RCS tools which support it. 216The state of a file/revision can be modified without having to check in 217a new file/revision. 218The default state is 219.Sq Exp 220(Experimental). 221Examples of states could be 222.Sq Dev , 223.Sq Reviewed , 224or 225.Sq Stab . 226.Pp 227In order to make large groups of RCS files more manageable, 228RCS tools have the ability to select files by their 229.Em symbolic name . 230Thus files can be selected by their symbolic name, 231rather than numerical revision. 232.Xr ci 1 233.Fl N 234and 235.Fl n 236are used to set symbolic names for files. 237.Pp 238The following methods of file selection are therefore available: 239revision number, state, and symbolic name. 240For options which take as argument 241.Ar rev 242or 243.Ar state , 244any of these methods may be used. 245Some examples: 246.Bd -literal -offset indent 247$ co -r"myproject" foo.c 248$ rcs -m1.3:update foo.c 249$ ci -s"Exp" bar.c 250.Ed 251.Sh KEYWORD SUBSTITUTION 252As long as source files are edited inside a working directory, 253their state can be determined using the 254.Xr cvs 1 255.Ic status 256or 257.Ic log 258commands, but as soon as files get exported from 259a local working copy, it becomes harder to identify which 260revisions they are. 261.Pp 262.Nm 263and 264.Xr cvs 1 265use a mechanism known as 266.Sq keyword substitution 267to help identify the files. 268Embedded strings of the form $keyword$ and $keyword:...$ in a file 269are replaced with strings of the form $keyword: value$ whenever 270a new revision of the file is obtained. 271The possible keywords are as follows: 272.Bl -tag -width "XrevisionXX" -offset "XXX" 273.It $\&Author$ 274The name of the user who checked in the revision. 275.It $\&Date$ 276The date and hour (UTC) the revision was checked in. 277.It $\&Header$ 278Standard header containing the full pathname of the RCS 279file, the revision number, the date (UTC), the author and the state. 280.It $\&Id$ and $\&OpenBSD$ 281The same content as $\&Header$ but without the path 282of the RCS file. 283.It $\&Log$ 284The log message supplied during commit, preceded by a header 285containing the RCS filename, the revision number, the 286author, and the date (UTC). 287.It $\&Mdocdate$ 288Produce a date of the form month name, day number, and year, 289suitable for the 290.Xr mdoc 7 291.Dq \&Dd 292macro. 293.It $\&Name$ 294The tag name used to check out the file. 295.It $\&RCSfile$ 296The name of the RCS file, but without a path. 297.It $\&Revision$ 298The revision number assigned to the revision. 299.It $\&Source$ 300The full pathname of the RCS file. 301.It $\&State$ 302The state assigned to the revision. 303.El 304.Pp 305Keyword substitution has its disadvantages: sometimes the 306literal text string $\&Author$ is wanted inside a file without 307.Nm 308or 309.Xr cvs 1 310interpreting it as a keyword and expanding it. 311The 312.Fl k Ns Ar o 313option can be used to turn off keyword substitution entirely though. 314There is unfortunately no way to selectively turn off keyword substitution. 315.Pp 316Each file and working directory copy of a file have a stored 317default substitution mode. 318Substitution modes on files are set by the 319.Fl k Ns Ar mode 320option. 321.Pp 322The possible substitution modes are as follows: 323.Bl -tag -width Ds -offset 3n 324.It Fl k Ns Ar b 325Like 326.Fl k Ns Ar o , 327but also avoids the conversion of line endings. 328This option is used to handle binary files. 329.It Fl k Ns Ar k 330Does not substitute the keywords. 331Useful with the 332.Xr cvs 1 333.Ic diff 334and 335.Xr rcsdiff 1 336commands to avoid displaying the differences between keyword substitutions. 337.It Fl k Ns Ar kv 338The default behaviour. 339Keywords are normally substituted i.e. $\&Revision$ becomes 340$\&Revision: 1.1 $. 341.It Fl k Ns Ar kvl 342Like 343.Fl k Ns Ar kv , 344except that the locker's name is displayed along with the version 345if the given revision is currently locked. 346This option is normally not useful as 347.Nm 348and 349.Xr cvs 1 350do not use file locking by default. 351.It Fl k Ns Ar o 352No substitutions are done. 353This option is often used with the 354.Xr cvs 1 355.Ic import 356command to guarantee that files that already contain external keywords 357do not get modified. 358.It Fl k Ns Ar v 359Substitute the value of keywords instead of keywords themselves 360e.g. instead of $\&Revision$, only insert 1.1 and not $\&Revision: 1.1 $. 361This option must be used with care, as it can only be used once. 362It is often used with the 363.Xr cvs 1 364.Ic export 365command to freeze the values before releasing software. 366.El 367.Sh ENVIRONMENT 368.Bl -tag -width RCSINIT 369.It Ev RCSINIT 370If set, this variable should contain a list of space-delimited options that 371are prepended to the argument list. 372.El 373.Sh EXIT STATUS 374.Ex -std rcs 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 cvs 1 , 445.Xr ident 1 , 446.Xr rcsclean 1 , 447.Xr rcsdiff 1 , 448.Xr rcsmerge 1 , 449.Xr rlog 1 450.Rs 451.%A Tichy, Walter F. 452.%T "RCS -- a system for version control" 453.%J "Software--Practice & Experience" 454.%V 15:7 455.%D July, 1985 456.%P pp. 637-654 457.Re 458.Sh STANDARDS 459OpenRCS is compatible with 460Walter Tichy's original RCS implementation. 461.Pp 462The flags 463.Op Fl Mz 464have no effect and are provided 465for compatibility only. 466.Sh HISTORY 467The OpenRCS project is a BSD-licensed rewrite of the original 468Revision Control System. 469OpenRCS is written by Jean-Francois Brousseau, Joris Vink, 470Niall O'Higgins, and Xavier Santolaria. 471.Pp 472The original RCS code was written in large parts by Walter F. Tichy 473and Paul Eggert. 474.Sh CAVEATS 475For historical reasons, 476the RCS tools do not permit whitespace between options and their arguments. 477