19Sjkh.de Id 29Sjkh.ds Rv \\$3 39Sjkh.ds Dt \\$4 49Sjkh.. 550472Speter.Id $FreeBSD$ 69Sjkh.ds r \&\s-1RCS\s0 79Sjkh.if n .ds - \%-- 89Sjkh.if t .ds - \(em 911891Speter.if !\n(.g \{\ 1011891Speter. if !\w|\*(lq| \{\ 1111891Speter. ds lq `` 1211891Speter. if \w'\(lq' .ds lq "\(lq 1311891Speter. \} 1411891Speter. if !\w|\*(rq| \{\ 1511891Speter. ds rq '' 1611891Speter. if \w'\(rq' .ds rq "\(rq 1711891Speter. \} 1811891Speter.\} 199Sjkh.am SS 209Sjkh.LP 219Sjkh.. 229Sjkh.TH RCSINTRO 1 \*(Dt GNU 239Sjkh.SH NAME 249Sjkhrcsintro \- introduction to RCS commands 259Sjkh.SH DESCRIPTION 269SjkhThe Revision Control System (\*r) manages multiple revisions of files. 279Sjkh\*r automates the storing, retrieval, logging, identification, and merging 289Sjkhof revisions. \*r is useful for text that is revised frequently, for example 299Sjkhprograms, documentation, graphics, papers, and form letters. 309Sjkh.PP 319SjkhThe basic user interface is extremely simple. The novice only needs 329Sjkhto learn two commands: 339Sjkh.BR ci (1) 349Sjkhand 359Sjkh.BR co (1). 369Sjkh.BR ci , 379Sjkhshort for \*(lqcheck in\*(rq, deposits the contents of a 389Sjkhfile into an archival file called an \*r file. An \*r file 399Sjkhcontains all revisions of a particular file. 409Sjkh.BR co , 419Sjkhshort for \*(lqcheck out\*(rq, retrieves revisions from an \*r file. 429Sjkh.SS "Functions of \*r" 439Sjkh.IP \(bu 449SjkhStore and retrieve multiple revisions of text. \*r saves all old 459Sjkhrevisions in a space efficient way. 469SjkhChanges no longer destroy the original, because the 479Sjkhprevious revisions remain accessible. Revisions can be retrieved according to 489Sjkhranges of revision numbers, symbolic names, dates, authors, and 499Sjkhstates. 509Sjkh.IP \(bu 519SjkhMaintain a complete history of changes. 529Sjkh\*r logs all changes automatically. 539SjkhBesides the text of each revision, \*r stores the author, the date and time of 549Sjkhcheck-in, and a log message summarizing the change. 559SjkhThe logging makes it easy to find out 569Sjkhwhat happened to a module, without having to compare 579Sjkhsource listings or having to track down colleagues. 589Sjkh.IP \(bu 599SjkhResolve access conflicts. When two or more programmers wish to 609Sjkhmodify the same revision, \*r alerts the programmers and prevents one 619Sjkhmodification from corrupting the other. 629Sjkh.IP \(bu 639SjkhMaintain a tree of revisions. \*r can maintain separate lines of development 649Sjkhfor each module. It stores a tree structure that represents the 659Sjkhancestral relationships among revisions. 669Sjkh.IP \(bu 679SjkhMerge revisions and resolve conflicts. 689SjkhTwo separate lines of development of a module can be coalesced by merging. 699SjkhIf the revisions to be merged affect the same sections of code, \*r alerts the 709Sjkhuser about the overlapping changes. 719Sjkh.IP \(bu 729SjkhControl releases and configurations. 739SjkhRevisions can be assigned symbolic names 749Sjkhand marked as released, stable, experimental, etc. 759SjkhWith these facilities, configurations of modules can be 769Sjkhdescribed simply and directly. 779Sjkh.IP \(bu 789SjkhAutomatically identify each revision with name, revision number, 799Sjkhcreation time, author, etc. 809SjkhThe identification is like a stamp that can be embedded at an appropriate place 819Sjkhin the text of a revision. 829SjkhThe identification makes it simple to determine which 839Sjkhrevisions of which modules make up a given configuration. 849Sjkh.IP \(bu 859SjkhMinimize secondary storage. \*r needs little extra space for 869Sjkhthe revisions (only the differences). If intermediate revisions are 879Sjkhdeleted, the corresponding deltas are compressed accordingly. 889Sjkh.SS "Getting Started with \*r" 899SjkhSuppose you have a file 909Sjkh.B f.c 919Sjkhthat you wish to put under control of \*r. 929SjkhIf you have not already done so, make an \*r directory with the command 939Sjkh.IP 949Sjkh.B "mkdir RCS" 959Sjkh.LP 969SjkhThen invoke the check-in command 979Sjkh.IP 989Sjkh.B "ci f.c" 999Sjkh.LP 1009SjkhThis command creates an \*r file in the 1019Sjkh.B RCS 1029Sjkhdirectory, 1039Sjkhstores 1049Sjkh.B f.c 1059Sjkhinto it as revision 1.1, and 1069Sjkhdeletes 1079Sjkh.BR f.c . 1089SjkhIt also asks you for a description. The description 1099Sjkhshould be a synopsis of the contents of the file. All later check-in 1109Sjkhcommands will ask you for a log entry, which should summarize the 1119Sjkhchanges that you made. 1129Sjkh.PP 1139SjkhFiles in the \*r directory are called \*r files; 1149Sjkhthe others are called working files. 1159SjkhTo get back the working file 1169Sjkh.B f.c 1179Sjkhin the previous example, use the check-out 1189Sjkhcommand 1199Sjkh.IP 1209Sjkh.B "co f.c" 1219Sjkh.LP 1229SjkhThis command extracts the latest revision from the \*r file 1239Sjkhand writes 1249Sjkhit into 1259Sjkh.BR f.c . 1269SjkhIf you want to edit 1279Sjkh.BR f.c , 1289Sjkhyou must lock it as you check it out with the command 1299Sjkh.IP 1309Sjkh.B "co \-l f.c" 1319Sjkh.LP 1329SjkhYou can now edit 1339Sjkh.BR f.c . 1349Sjkh.PP 1359SjkhSuppose after some editing you want to know what changes that you have made. 1369SjkhThe command 1379Sjkh.IP 1389Sjkh.B "rcsdiff f.c" 1399Sjkh.LP 1409Sjkhtells you the difference between the most recently checked-in version 1419Sjkhand the working file. 1429SjkhYou can check the file back in by invoking 1439Sjkh.IP 1449Sjkh.B "ci f.c" 1459Sjkh.LP 1469SjkhThis increments the revision number properly. 1479Sjkh.PP 1489SjkhIf 1499Sjkh.B ci 1509Sjkhcomplains with the message 1519Sjkh.IP 1529Sjkh.BI "ci error: no lock set by " "your name" 1539Sjkh.LP 1549Sjkhthen you have tried to check in a file even though you did not 1559Sjkhlock it when you checked it out. 1569SjkhOf course, it is too late now to do the check-out with locking, because 1579Sjkhanother check-out would 1589Sjkhoverwrite your modifications. Instead, invoke 1599Sjkh.IP 1609Sjkh.B "rcs \-l f.c" 1619Sjkh.LP 1629SjkhThis command will lock the latest revision for you, unless somebody 1639Sjkhelse got ahead of you already. In this case, you'll have to negotiate with 1649Sjkhthat person. 1659Sjkh.PP 1669SjkhLocking assures that you, and only you, can check in the next update, and 1679Sjkhavoids nasty problems if several people work on the same file. 1689SjkhEven if a revision is locked, it can still be checked out for 1699Sjkhreading, compiling, etc. All that locking 1709Sjkhprevents is a 1719Sjkh.I "check-in" 1729Sjkhby anybody but the locker. 1739Sjkh.PP 1749SjkhIf your \*r file is private, i.e., if you are the only person who is going 1759Sjkhto deposit revisions into it, strict locking is not needed and you 1769Sjkhcan turn it off. 1779SjkhIf strict locking is turned off, 1789Sjkhthe owner of the \*r file need not have a lock for check-in; all others 1799Sjkhstill do. Turning strict locking off and on is done with the commands 1809Sjkh.IP 1819Sjkh.BR "rcs \-U f.c" " and " "rcs \-L f.c" 1829Sjkh.LP 1839SjkhIf you don't want to clutter your working directory with \*r files, create 1849Sjkha subdirectory called 1859Sjkh.B RCS 1869Sjkhin your working directory, and move all your \*r 1879Sjkhfiles there. \*r commands will look first into that directory to find 1889Sjkhneeded files. All the commands discussed above will still work, without any 1899Sjkhmodification. 1909Sjkh(Actually, pairs of \*r and working files can be specified in three ways: 1919Sjkh(a) both are given, (b) only the working file is given, (c) only the 1929Sjkh\*r file is given. Both \*r and working files may have arbitrary path prefixes; 1939Sjkh\*r commands pair them up intelligently.) 1949Sjkh.PP 1959SjkhTo avoid the deletion of the working file during check-in (in case you want to 1969Sjkhcontinue editing or compiling), invoke 1979Sjkh.IP 1989Sjkh.BR "ci \-l f.c" " or " "ci \-u f.c" 1999Sjkh.LP 2009SjkhThese commands check in 2019Sjkh.B f.c 2029Sjkhas usual, but perform an implicit 2039Sjkhcheck-out. The first form also locks the checked in revision, the second one 2049Sjkhdoesn't. Thus, these options save you one check-out operation. 2059SjkhThe first form is useful if you want to continue editing, 2069Sjkhthe second one if you just want to read the file. 2079SjkhBoth update the identification markers in your working file (see below). 2089Sjkh.PP 2099SjkhYou can give 2109Sjkh.B ci 2119Sjkhthe number you want assigned to a checked in 2129Sjkhrevision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., 2139Sjkhand you would like to start release 2. 2149SjkhThe command 2159Sjkh.IP 2169Sjkh.BR "ci \-r2 f.c" " or " "ci \-r2.1 f.c" 2179Sjkh.LP 2189Sjkhassigns the number 2.1 to the new revision. 2199SjkhFrom then on, 2209Sjkh.B ci 2219Sjkhwill number the subsequent revisions 2229Sjkhwith 2.2, 2.3, etc. The corresponding 2239Sjkh.B co 2249Sjkhcommands 2259Sjkh.IP 2269Sjkh.BR "co \-r2 f.c" " and " "co \-r2.1 f.c" 2279Sjkh.PP 2289Sjkhretrieve the latest revision numbered 2299Sjkh.RI 2. x 2309Sjkhand the revision 2.1, 2319Sjkhrespectively. 2329Sjkh.B co 2339Sjkhwithout a revision number selects 2349Sjkhthe latest revision on the 2359Sjkh.IR trunk , 2369Sjkhi.e. the highest 2379Sjkhrevision with a number consisting of two fields. Numbers with more than two 2389Sjkhfields are needed for branches. 2399SjkhFor example, to start a branch at revision 1.3, invoke 2409Sjkh.IP 2419Sjkh.B "ci \-r1.3.1 f.c" 2429Sjkh.LP 2439SjkhThis command starts a branch numbered 1 at revision 1.3, and assigns 2449Sjkhthe number 1.3.1.1 to the new revision. For more information about 2459Sjkhbranches, see 2469Sjkh.BR rcsfile (5). 2479Sjkh.SS "Automatic Identification" 2489Sjkh\*r can put special strings for identification into your source and object 2499Sjkhcode. To obtain such identification, place the marker 2509Sjkh.IP 2519Sjkh.B "$\&Id$" 2529Sjkh.LP 2539Sjkhinto your text, for instance inside a comment. 2549Sjkh\*r will replace this marker with a string of the form 2559Sjkh.IP 2569Sjkh.BI $\&Id: " filename revision date time author state " $ 2579Sjkh.LP 2589SjkhWith such a marker on the first page of each module, you can 2599Sjkhalways see with which revision you are working. 2609Sjkh\*r keeps the markers up to date automatically. 2619SjkhTo propagate the markers into your object code, simply put 2629Sjkhthem into literal character strings. In C, this is done as follows: 2639Sjkh.IP 2649Sjkh.ft 3 2659Sjkhstatic char rcsid[] = \&"$\&Id$\&"; 2669Sjkh.ft 2679Sjkh.LP 2689SjkhThe command 2699Sjkh.B ident 2709Sjkhextracts such markers from any file, even object code 2719Sjkhand dumps. 2729SjkhThus, 2739Sjkh.B ident 2749Sjkhlets you find out 2759Sjkhwhich revisions of which modules were used in a given program. 2769Sjkh.PP 2779SjkhYou may also find it useful to put the marker 2789Sjkh.B $\&Log$ 2799Sjkhinto your text, inside a comment. This marker accumulates 2809Sjkhthe log messages that are requested during check-in. 2819SjkhThus, you can maintain the complete history of your file directly inside it. 2829SjkhThere are several additional identification markers; see 2839Sjkh.BR co (1) 2849Sjkhfor 2859Sjkhdetails. 2869Sjkh.SH IDENTIFICATION 2879SjkhAuthor: Walter F. Tichy. 2889Sjkh.br 28911891SpeterManual Page Revision: \*(Rv; Release Date: \*(Dt. 2909Sjkh.br 29111891SpeterCopyright \(co 1982, 1988, 1989 Walter F. Tichy. 2929Sjkh.br 29311891SpeterCopyright \(co 1990, 1991, 1992, 1993 Paul Eggert. 2949Sjkh.SH "SEE ALSO" 2959Sjkhci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1) 2969Sjkh.br 2979SjkhWalter F. Tichy, 2989Sjkh\*r\*-A System for Version Control, 2999Sjkh.I "Software\*-Practice & Experience" 3009Sjkh.BR 15 , 3019Sjkh7 (July 1985), 637-654. 3029Sjkh.br 303