.\" Format this file with:.\" pic file | tbl | troff -ms.\".\" \*s stands for $, and avoids problems when this file is checked in..EH 'PSD:13-%''RCS \*- A System for Version Control'.OH 'RCS \*- A System for Version Control''PSD:13-%'.ds s $.\" PS and PE center pic diagrams. (The corresponding ms-macros may not.).de PS.nr pE (\\n(.lu-\\$2u)/2u.in +\\n(pEu.ne \\$1u...de PE.in -\\n(pEu...de D(.DS.nr VS 12p.vs 12p.I...de D).DE.nr VS 18p.vs 18p.R...de Id.ND \\$4...Id $Id: rcs.ms,v 5.2 1991/01/03 10:57:28 eggert Exp $.RP.TLRCS\*-A System for Version Control.sp.AUWalter F. Tichy.AIDepartment of Computer SciencesPurdue UniversityWest Lafayette, Indiana 47907.sp.ABAn important problem in program development and maintenance is version control,i.e., the task of keeping a software system consisting of many versions andconfigurations well organized.The Revision Control System (RCS)is a software tool that assists with that task.RCS manages revisions of text documents, in particular source programs,documentation, and test data.It automates the storing, retrieval, logging and identification of revisions,and it provides selection mechanisms for composing configurations.This paper introduces basic version control concepts anddiscusses the practice of version controlusing RCS.For conserving space, RCS stores deltas, i.e., differences betweensuccessive revisions.  Several delta storage methods are discussed.Usage statistics show that RCS's delta storage method isspace and time efficient.The paper concludes with a detailed survey of version control tools..sp\fBKeywords\fR: configuration management, history management,version control, revisions, deltas..AE.FSAn earlier version of this paper was published in.I "Software\*-Practice & Experience".B 15 ,7 (July 1985), 637-654..FE.nr VS 18p.LP.NHIntroduction.PPVersion control is the task of keeping softwaresystems consisting of many versions and configurations well organized.The Revision Control System (RCS) is a set of UNIXcommands that assist with that task..PPRCS' primary function is to manage \fIrevision groups\fR.A revision group is a set of text documents, called \fIrevisions\fR,that evolved from each other.  A new revision iscreated by manually editing an existing one.RCS organizes the revisions into an ancestral tree.  The initial revisionis the root of the tree, and the tree edges indicatefrom which revision a given one evolved.Besides managing individual revision groups, RCS providesflexible selection functions for composing configurations.RCS may be combined with MAKE\u1\d,resulting in a powerful package for version control..PPRCS also offers facilities formerging updates with customer modifications,for distributed software development, andfor automatic identification.Identification is the `stamping'of revisions and configurations with unique markers.These markers are akin to serial numbers,telling software maintainers unambiguously which configurationis before them..PPRCS is designed for both production and experimentalenvironments.In production environments,access controls detect update conflicts and prevent overlapping changes.In experimental environments, where strong controls arecounterproductive, it is possible to loosen the controls..PPAlthough RCS was originally intended for programs, it is useful for anytext that is revised frequently and whose previous revisions must bepreserved.  RCS has been applied successfully to store the sourcetext for drawings, VLSI layouts, documentation, specifications,test data, form letters and articles..PPThis paper discusses the practice ofversion control using RCS.It also introduces basic version control concepts,useful for clarifying current practice and designing similar systems.Revision groups of individual components are treated in the next three sections,and the extensions to configurations follow.Because of its size, a survey of version control toolsappears at the end of the paper..NHGetting started with RCS.PPSuppose a text file \fIf.c\fR is to be placed under control of RCS.Invoking the check-in command.D(ci  f.c.D)creates a new revision group with the contents of\fIf.c\fR as the initialrevision (numbered 1.1)and stores the group into the file \fIf.c,v\fR.Unless told otherwise, the command deletes \fIf.c\fR.It also asks for a description of the group.The description should state the common purpose of all revisions in the group,and becomes part of the group's documentation.All later check-in commands will ask for a log entry,which should summarize the changes made.(The first revision is assigned a default log message,which just records the fact that it is the initial revision.).PPFiles ending in \fI,v\fRare called \fIRCS files\fR (\fIv\fR stands for \fIv\fRersions);the others are called working files.To get back the working file \fIf.c\fR in the previous example,execute the check-out command:.D(co  f.c.D).RThis command extracts the latest revision fromthe revision group \fIf.c,v\fR and writesit into \fIf.c\fR.The file \fIf.c\fR can now be edited and, when finished,checked back in with \fIci\fR:.D(ci  f.c.D)\fICi\fR assigns number 1.2 tothe new revision.If \fIci\fR complains with the message.D(ci error: no lock set by <login>.D)then the system administrator has decided to configure RCS for aproduction environment by enabling the `strict locking feature'.If this feature is enabled, all RCS files are initializedsuch that check-in operations require a lock on the previous revision(the one from which the current one evolved).Locking prevents overlapping modifications if several people work on the same file.If locking is required, the revision shouldhave been locked during the check-out by usingthe option \fI\-l\fR:.D(co  \-l  f.c.D)Of course it is too late now for the check-out with locking, because\fIf.c\fR has already been changed; checking out the file againwould overwrite the modifications.(To prevent accidental overwrites, \fIco\fR senses the presenceof a working file and asks whether the user really intended to overwrite it.The overwriting check-out is sometimes useful forbacking up to the previous revision.)To be able to proceed with the check-in in the present case, first execute.D(rcs  \-l  f.c.D)This command retroactively locks the latest revision, unless someoneelse locked it in the meantime.  In this case, the two programmersinvolved have to negotiate whosemodifications should take precedence..PPIf an RCS file is private, i.e., if only the owner of the file is expectedto deposit revisions into it, the strict locking feature is unnecessary andmay be disabled.If strict locking is disabled,the owner of the RCS file need not have a lock for check-in.For safety reasons, all othersstill do.  Turning strict locking off and on is done with the commands:.D(rcs  \-U  f.c       \fRand\fP         rcs  \-L  f.c.D)These commands enable or disable the strict locking feature for each RCS fileindividually.The system administrator only decides whether strict locking isenabled initially..PPTo reduce the clutter in a working directory, all RCS files can be movedto a subdirectory with the name \fIRCS\fR.RCS commands look first into that directory for RCS files.All the commands presented above workwith the \fIRCS\fR subdirectory without change.\(dg.FS \(dgPairs of RCS and working files can actually be specified in 3 ways:a) both are given, b) only the working file is given, c) only theRCS file is given.If a pair is given, both files may have arbitrary path prefixes;RCS commands pair them up intelligently..FE.PPIt may be undesirable that \fIci\fR deletes the working file.For instance, sometimes one would like to save the current revision,but continue editing.Invoking.D(ci  \-l  f.c.D)checks in \fIf.c\fR as usual, but performs an additionalcheck-out with locking afterwards.  Thus, the working file doesnot disappear after the check-in.Similarly, the option\fI\-u\fR does a check-in followed by a check-out withoutlocking.  This option is useful if the file is needed for compilation after the check-in.Both options update the identification markers in the working file(see below)..PPBesides the operations \fIci\fR and \fIco\fR, RCS provides the followingcommands:.sp 0.nr VS 12p.vs 12p.TStab(%);li l.ident%extract identification markersrcs%change RCS file attributesrcsclean%remove unchanged working files (optional)rcsdiff%compare revisionsrcsfreeze%record a configuration (optional)rcsmerge%merge revisionsrlog%read log messages and other information in RCS files.TEA synopsis of these commands appears in the Appendix..NH 2Automatic Identification.PPRCS can stamp source and object code with special identification strings,similar to product and serial numbers.To obtain such identification, place the marker.D(\*sId\*s.D)into the text of a revision, for instance inside a comment.The check-out operation will replace this marker with a string of the form.D(\*sId:  filename  revisionnumber  date  time  author  state  locker \*s.D)This string need never be touched, because \fIco\fR keeps itup to date automatically.To propagate the marker into object code, simply putit into a literal character string.  In C, this is done as follows:.D(static char rcsid[] = \&"\*sId\*s\&";.D)The command \fIident\fR extracts such markers from any file, in particular fromobject code.\fIIdent\fR helps to find outwhich revisions of which modules were used in a given program.It returns a complete and unambiguous component list,from which a copy of the program can be reconstructed.This facility is invaluable for program maintenance..PPThere are several additional identification markers, one for each componentof \*sId\*s.The marker.D(\*sLog\*s.D)has a similar function.  It accumulatesthe log messages that are requested during check-in.Thus, one can maintain the complete history of a revision directly inside it,by enclosing it in a comment.Figure 1 is a partial reproduction of a log contained in revision 4.1 ofthe file \fIci.c\fR.  The log appears at the beginning of the file,and makes it easy to determine what the recent modifications were..sp.nr VS 12p.vs 12p.ne 18.nf.in +0.5i/* \*sLog: ci.c,v \*s * Revision 4.1  1983/05/10  17:03:06  wft * Added option \-d and \-w, and updated assignment of date, etc. to new delta. * Added handling of default branches. * * Revision 3.9  1983/02/15  15:25:44  wft * Added call to fastcopy() to copy remainder of RCS file. * * Revision 3.8  1983/01/14  15:34:05  wft * Added ignoring of interrupts while new RCS file is renamed; * avoids deletion of RCS files by interrupts. * * Revision 3.7  1982/12/10  16:09:20  wft * Corrected checking of return code from diff. * An RCS file now inherits its mode during the first ci from the working file, * except that write permission is removed. */.in 0.ce 1Figure 1.  Log entries produced by the marker \*sLog\*s..fi.nr VS 18p.vs 18p.sp 0.LPSince revisions are stored in the form of differences,each log message isphysically stored once,independent of the number of revisions present.Thus, the \*sLog\*s marker incurs negligible space overhead..NHThe RCS Revision Tree.PPRCS arranges revisions in an ancestral tree.The \fIci\fR command builds this tree; the auxiliary command \fIrcs\fRprunes it.The tree has a root revision, normally numbered 1.1, and successive revisionsare numbered 1.2, 1.3, etc.  The first field of a revision numberis called the \fIrelease number\fR and the second onethe \fIlevel number\fR.  Unless given explicitly,the \fIci\fR command assigns a new revision numberby incrementing the level number of the previous revision.The release number must be incremented explicitly, using the\fI\-r\fR option of \fIci\fR.Assuming there are revisions 1.1, 1.2, and 1.3 in the RCS file f.c,v, the command.D(ci  \-r2.1  f.c       \fRor\fP       ci  \-r2  f.c.D)assigns the number 2.1 to the new revision.Later check-ins without the \fI\-r\fR option will assign the numbers 2.2, 2.3,and so on.The release number should be incremented only at major transition pointsin the development, for instance when a new release of a software product hasbeen completed..NH 2When are branches needed?.PPA young revision tree is slender:It consists of only one branch, called the trunk.As the tree ages, side branches may form.Branches are needed in the following 4 situations..IP "\fITemporary fixes\fR".sp 0Suppose a tree has 5 revisions grouped in 2 releases,as illustrated in Figure 2.Revision 1.3, the last one of release 1, is in operation at customer sites,while release 2 is in active development..ne 4.PS 4i.ps -2box "1.1"arrowbox "1.2"arrowbox "1.3"arrowbox "2.1"