1.de Id 2.ds Rv \\$3 3.ds Dt \\$4 4.. 5.Id $FreeBSD$ 6.ds r \&\s-1RCS\s0 7.if n .ds - \%-- 8.if t .ds - \(em 9.if !\n(.g \{\ 10. if !\w|\*(lq| \{\ 11. ds lq `` 12. if \w'\(lq' .ds lq "\(lq 13. \} 14. if !\w|\*(rq| \{\ 15. ds rq '' 16. if \w'\(rq' .ds rq "\(rq 17. \} 18.\} 19.am SS 20.LP 21.. 22.TH RCSINTRO 1 \*(Dt GNU 23.SH NAME 24rcsintro \- introduction to RCS commands 25.SH DESCRIPTION 26The Revision Control System (\*r) manages multiple revisions of files. 27\*r automates the storing, retrieval, logging, identification, and merging 28of revisions. \*r is useful for text that is revised frequently, for example 29programs, documentation, graphics, papers, and form letters. 30.PP 31The basic user interface is extremely simple. The novice only needs 32to learn two commands: 33.BR ci (1) 34and 35.BR co (1). 36.BR ci , 37short for \*(lqcheck in\*(rq, deposits the contents of a 38file into an archival file called an \*r file. An \*r file 39contains all revisions of a particular file. 40.BR co , 41short for \*(lqcheck out\*(rq, retrieves revisions from an \*r file. 42.SS "Functions of \*r" 43.IP \(bu 44Store and retrieve multiple revisions of text. \*r saves all old 45revisions in a space efficient way. 46Changes no longer destroy the original, because the 47previous revisions remain accessible. Revisions can be retrieved according to 48ranges of revision numbers, symbolic names, dates, authors, and 49states. 50.IP \(bu 51Maintain a complete history of changes. 52\*r logs all changes automatically. 53Besides the text of each revision, \*r stores the author, the date and time of 54check-in, and a log message summarizing the change. 55The logging makes it easy to find out 56what happened to a module, without having to compare 57source listings or having to track down colleagues. 58.IP \(bu 59Resolve access conflicts. When two or more programmers wish to 60modify the same revision, \*r alerts the programmers and prevents one 61modification from corrupting the other. 62.IP \(bu 63Maintain a tree of revisions. \*r can maintain separate lines of development 64for each module. It stores a tree structure that represents the 65ancestral relationships among revisions. 66.IP \(bu 67Merge revisions and resolve conflicts. 68Two separate lines of development of a module can be coalesced by merging. 69If the revisions to be merged affect the same sections of code, \*r alerts the 70user about the overlapping changes. 71.IP \(bu 72Control releases and configurations. 73Revisions can be assigned symbolic names 74and marked as released, stable, experimental, etc. 75With these facilities, configurations of modules can be 76described simply and directly. 77.IP \(bu 78Automatically identify each revision with name, revision number, 79creation time, author, etc. 80The identification is like a stamp that can be embedded at an appropriate place 81in the text of a revision. 82The identification makes it simple to determine which 83revisions of which modules make up a given configuration. 84.IP \(bu 85Minimize secondary storage. \*r needs little extra space for 86the revisions (only the differences). If intermediate revisions are 87deleted, the corresponding deltas are compressed accordingly. 88.SS "Getting Started with \*r" 89Suppose you have a file 90.B f.c 91that you wish to put under control of \*r. 92If you have not already done so, make an \*r directory with the command 93.IP 94.B "mkdir RCS" 95.LP 96Then invoke the check-in command 97.IP 98.B "ci f.c" 99.LP 100This command creates an \*r file in the 101.B RCS 102directory, 103stores 104.B f.c 105into it as revision 1.1, and 106deletes 107.BR f.c . 108It also asks you for a description. The description 109should be a synopsis of the contents of the file. All later check-in 110commands will ask you for a log entry, which should summarize the 111changes that you made. 112.PP 113Files in the \*r directory are called \*r files; 114the others are called working files. 115To get back the working file 116.B f.c 117in the previous example, use the check-out 118command 119.IP 120.B "co f.c" 121.LP 122This command extracts the latest revision from the \*r file 123and writes 124it into 125.BR f.c . 126If you want to edit 127.BR f.c , 128you must lock it as you check it out with the command 129.IP 130.B "co \-l f.c" 131.LP 132You can now edit 133.BR f.c . 134.PP 135Suppose after some editing you want to know what changes that you have made. 136The command 137.IP 138.B "rcsdiff f.c" 139.LP 140tells you the difference between the most recently checked-in version 141and the working file. 142You can check the file back in by invoking 143.IP 144.B "ci f.c" 145.LP 146This increments the revision number properly. 147.PP 148If 149.B ci 150complains with the message 151.IP 152.BI "ci error: no lock set by " "your name" 153.LP 154then you have tried to check in a file even though you did not 155lock it when you checked it out. 156Of course, it is too late now to do the check-out with locking, because 157another check-out would 158overwrite your modifications. Instead, invoke 159.IP 160.B "rcs \-l f.c" 161.LP 162This command will lock the latest revision for you, unless somebody 163else got ahead of you already. In this case, you'll have to negotiate with 164that person. 165.PP 166Locking assures that you, and only you, can check in the next update, and 167avoids nasty problems if several people work on the same file. 168Even if a revision is locked, it can still be checked out for 169reading, compiling, etc. All that locking 170prevents is a 171.I "check-in" 172by anybody but the locker. 173.PP 174If your \*r file is private, i.e., if you are the only person who is going 175to deposit revisions into it, strict locking is not needed and you 176can turn it off. 177If strict locking is turned off, 178the owner of the \*r file need not have a lock for check-in; all others 179still do. Turning strict locking off and on is done with the commands 180.IP 181.BR "rcs \-U f.c" " and " "rcs \-L f.c" 182.LP 183If you don't want to clutter your working directory with \*r files, create 184a subdirectory called 185.B RCS 186in your working directory, and move all your \*r 187files there. \*r commands will look first into that directory to find 188needed files. All the commands discussed above will still work, without any 189modification. 190(Actually, pairs of \*r and working files can be specified in three ways: 191(a) both are given, (b) only the working file is given, (c) only the 192\*r file is given. Both \*r and working files may have arbitrary path prefixes; 193\*r commands pair them up intelligently.) 194.PP 195To avoid the deletion of the working file during check-in (in case you want to 196continue editing or compiling), invoke 197.IP 198.BR "ci \-l f.c" " or " "ci \-u f.c" 199.LP 200These commands check in 201.B f.c 202as usual, but perform an implicit 203check-out. The first form also locks the checked in revision, the second one 204doesn't. Thus, these options save you one check-out operation. 205The first form is useful if you want to continue editing, 206the second one if you just want to read the file. 207Both update the identification markers in your working file (see below). 208.PP 209You can give 210.B ci 211the number you want assigned to a checked in 212revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., 213and you would like to start release 2. 214The command 215.IP 216.BR "ci \-r2 f.c" " or " "ci \-r2.1 f.c" 217.LP 218assigns the number 2.1 to the new revision. 219From then on, 220.B ci 221will number the subsequent revisions 222with 2.2, 2.3, etc. The corresponding 223.B co 224commands 225.IP 226.BR "co \-r2 f.c" " and " "co \-r2.1 f.c" 227.PP 228retrieve the latest revision numbered 229.RI 2. x 230and the revision 2.1, 231respectively. 232.B co 233without a revision number selects 234the latest revision on the 235.IR trunk , 236i.e. the highest 237revision with a number consisting of two fields. Numbers with more than two 238fields are needed for branches. 239For example, to start a branch at revision 1.3, invoke 240.IP 241.B "ci \-r1.3.1 f.c" 242.LP 243This command starts a branch numbered 1 at revision 1.3, and assigns 244the number 1.3.1.1 to the new revision. For more information about 245branches, see 246.BR rcsfile (5). 247.SS "Automatic Identification" 248\*r can put special strings for identification into your source and object 249code. To obtain such identification, place the marker 250.IP 251.B "$\&Id$" 252.LP 253into your text, for instance inside a comment. 254\*r will replace this marker with a string of the form 255.IP 256.BI $\&Id: " filename revision date time author state " $ 257.LP 258With such a marker on the first page of each module, you can 259always see with which revision you are working. 260\*r keeps the markers up to date automatically. 261To propagate the markers into your object code, simply put 262them into literal character strings. In C, this is done as follows: 263.IP 264.ft 3 265static char rcsid[] = \&"$\&Id$\&"; 266.ft 267.LP 268The command 269.B ident 270extracts such markers from any file, even object code 271and dumps. 272Thus, 273.B ident 274lets you find out 275which revisions of which modules were used in a given program. 276.PP 277You may also find it useful to put the marker 278.B $\&Log$ 279into your text, inside a comment. This marker accumulates 280the log messages that are requested during check-in. 281Thus, you can maintain the complete history of your file directly inside it. 282There are several additional identification markers; see 283.BR co (1) 284for 285details. 286.SH IDENTIFICATION 287Author: Walter F. Tichy. 288.br 289Manual Page Revision: \*(Rv; Release Date: \*(Dt. 290.br 291Copyright \(co 1982, 1988, 1989 Walter F. Tichy. 292.br 293Copyright \(co 1990, 1991, 1992, 1993 Paul Eggert. 294.SH "SEE ALSO" 295ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1) 296.br 297Walter F. Tichy, 298\*r\*-A System for Version Control, 299.I "Software\*-Practice & Experience" 300.BR 15 , 3017 (July 1985), 637-654. 302.br 303