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