v89i220: rcs - revision control system, Part05/14

[Bob Page]

Submitted-by: rs...@cbmvax.commodore.com (Raymond S. Brand)
Posting-number: Volume 89, Issue 220
Archive-name: unix/rcs.05

# This is a shell archive.
# Remove anything above and including the cut line.
# Then run the rest of the file through 'sh'.
# Unpacked files will be owned by you and have default permissions.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar: SHell ARchive
# Run the following text through 'sh' to create:
# doc/rcs.ms
# doc/rcs_functs.ms
# doc/ci.1l
# doc/co.1l
# doc/ident.1l
# doc/merge.1l
# This is archive 5 of a 14-part kit.
# This archive created: Sun Nov 19 01:12:06 1989
if `test ! -d doc`
then
mkdir doc
echo "mkdir doc"
fi
echo "extracting doc/rcs.ms"
sed 's/^X//' << \SHAR_EOF > doc/rcs.ms
X.\ Format this file with:
X.\ pic file | tbl | troff -ms
X
X.\ PS and PE center pic diagrams. (The corresponding ms-macros may not.)
X.de PS
X.nr pE (\\n(.lu-\\$2u)/2u
X.in +\\n(pEu
X.ne \\$1u
X..
X.de PE
X.in -\\n(pEu
X..
X.de D(
X.DS
X.nr VS 12pts
X.vs 12pts
X.I
X..
X.de D)
X.DE
X.nr VS 18pts
X.vs 18pts
X.R
X..
X
X.ND July 1985
X.RP
X.TL
XRCS \- A System for Version Control
X
X.AU
XWalter F. Tichy
X.AI
XDepartment of Computer Sciences
XPurdue University
XWest Lafayette, Indiana 47907
X
X.AB
XAn important problem in program development and maintenance is version control,
Xi.e., the task of keeping a software system consisting of many versions and
Xconfigurations well organized.
XThe Revision Control System (RCS)
Xis a software tool that assists with that task.
XRCS manages revisions of text documents, in particular source programs,
Xdocumentation, and test data.
XIt automates the storing, retrieval, logging and identification of revisions,
Xand it provides selection mechanisms for composing configurations.
XThis paper introduces basic version control concepts and
Xdiscusses the practice of version control
Xusing RCS.
XFor conserving space, RCS stores deltas, i.e., differences between
Xsuccessive revisions. Several delta storage methods are discusses.
XUsage statistics show that RCS's delta storage method is
Xspace and time efficient.
XThe paper concludes with a detailed survey of version control tools.
X
X\fBKeywords\fR: configuration management, history management,
Xversion control, revisions, deltas.
X.AE
X.FS
XA version of this paper was published in Software--Practice and Experience,
XVol. 15(7), 637-654 (July 1985).
X.FE
X.nr VS 18pts
X.EQ
Xdelim $$
X.EN
X.LP
X.NH
XIntroduction
X.PP
XVersion control is the task of keeping software
Xsystems consisting of many versions and configurations well organized.
XThe Revision Control System (RCS) is a set of UNIX
Xcommands that assist with that task.
X.PP
XRCS' primary function is to manage \fIrevision groups\fR.
XA revision group is a set of text documents, called \fIrevisions\fR,
Xthat evolved from each other. A new revision is
Xcreated by manually editing an existing one.
XRCS organizes the revisions into an ancestral tree. The initial revision
Xis the root of the tree, and the tree edges indicate
Xfrom which revision a given one evolved.
XBesides managing individual revision groups, RCS provides
Xflexible selection functions for composing configurations.
XRCS may be combined with MAKE\u1\d,
Xresulting in a powerful package for version control.
X.PP
XRCS also offers facilities for
Xmerging updates with customer modifications,
Xfor distributed software development, and
Xfor automatic identification.
XIdentification is the `stamping'
Xof revisions and configurations with unique markers.
XThese markers are akin to serial numbers,
Xtelling software maintainers unambiguously which configuration
Xis before them.
X.PP
XRCS is designed for both production and experimental
Xenvironments.
XIn production environments,
Xaccess controls detect update conflicts and prevent overlapping changes.
XIn experimental environments, where strong controls are
Xcounterproductive, it is possible to loosen the controls.
X.PP
XAlthough RCS was originally intended for programs, it is useful for any
Xtext that is revised frequently and whose previous revisions must be
Xpreserved. RCS has been applied successfully to store the source
Xtext for drawings, VLSI layouts, documentation, specifications,
Xtest data, form letters and articles.
X.PP
XThis paper discusses the practice of
Xversion control using RCS.
XIt also introduces basic version control concepts,
Xuseful for clarifying current practice and designing similar systems.
XRevision groups of individual components are treated in the next three sections,
Xand the extensions to configurations follow.
XBecause of its size, a survey of version control tools
Xappears at the end of the paper.
X.NH
XGetting started with RCS
X.PP
XSuppose a text file \fIf.c\fR is to be placed under control of RCS.
XInvoking the check-in command
X.D(
Xci f.c
X.D)
Xcreates a new revision group with the contents of
X\fIf.c\fR as the initial
Xrevision (numbered 1.1)
Xand stores the group into the file \fIf.c,v\fR.
XUnless told otherwise, the command deletes \fIf.c\fR.
XIt also asks for a description of the group.
XThe description should state the common purpose of all revisions in the group,
Xand becomes part of the group's documentation.
XAll later check-in commands will ask for a log entry,
Xwhich should summarize the changes made.
X(The first revision is assigned a default log message,
Xwhich just records the fact that it is the initial revision.)
X.PP
XFiles ending in \fI,v\fR
Xare called \fIRCS files\fR (\fIv\fR stands for \fIv\fRersions);
Xthe others are called working files.
XTo get back the working file \fIf.c\fR in the previous example,
Xexecute the check-out command:
X.D(
Xco f.c
X.D)
X.R
XThis command extracts the latest revision from
Xthe revision group \fIf.c,v\fR and writes
Xit into \fIf.c\fR.
XThe file \fIf.c\fR can now be edited and, when finished,
Xchecked back in with \fIci\fR:
X.D(
Xci f.c
X.D)
X\fICi\fR assigns number 1.2 to
Xthe new revision.
XIf \fIci\fR complains with the message
X.D(
Xci error: no lock set by <login>
X.D)
Xthen the system administrator has decided to configure RCS for a
Xproduction environment by enabling the `strict locking feature'.
XIf this feature is enabled, all RCS files are initialized
Xsuch that check-in operations require a lock on the previous revision
X(the one from which the current one evolved).
XLocking prevents overlapping modifications if several people work on the same file.
XIf locking is required, the revision should
Xhave been locked during the check-out by using
Xthe option \fI-l\fR:
X.D(
Xco -l f.c
X.D)
XOf course it is too late now for the check-out with locking, because
X\fIf.c\fR has already been changed; checking out the file again
Xwould overwrite the modifications.
X(To prevent accidental overwrites, \fIco\fR senses the presence
Xof a working file and asks whether the user really intended to overwrite it.
XThe overwriting check-out is sometimes useful for
Xbacking up to the previous revision.)
XTo be able to proceed with the check-in in the present case, first execute
X.D(
Xrcs -l f.c
X.D)
XThis command retroactively locks the latest revision, unless someone
Xelse locked it in the meantime. In this case, the two programmers
Xinvolved have to negotiate whose
Xmodifications should take precedence.
X.PP
XIf an RCS file is private, i.e., if only the owner of the file is expected
Xto deposit revisions into it, the strict locking feature is unnecessary and
Xmay be disabled.
XIf strict locking is disabled,
Xthe owner of the RCS file need not have a lock for check-in.
XFor safety reasons, all others
Xstill do. Turning strict locking off and on is done with the commands:
X.D(
Xrcs -U f.c \fRand\fI rcs -L f.c
X.D)
XThese commands enable or disable the strict locking feature for each RCS file
Xindividually.
XThe system administrator only decides whether strict locking is
Xenabled initially.
X.PP
XTo reduce the clutter in a working directory, all RCS files can be moved
Xto a subdirectory with the name \fIRCS\fR.
XRCS commands look first into that directory for RCS files.
XAll the commands presented above work
Xwith the \fIRCS\fR subdirectory without change.\(dg
X.FS
X\(dg Pairs of RCS and working files can actually be specified in 3 ways:
Xa) both are given, b) only the working file is given, c) only the
XRCS file is given.
XIf a pair is given, both files may have arbitrary path prefixes;
XRCS commands pair them up intelligently.
X.FE
X.PP
XIt may be undesirable that \fIci\fR deletes the working file.
XFor instance, sometimes one would like to save the current revision,
Xbut continue editing.
XInvoking
X.D(
Xci -l f.c
X.D)
Xchecks in \fIf.c\fR as usual, but performs an additional
Xcheck-out with locking afterwards. Thus, the working file does
Xnot disappear after the check-in.
XSimilarly, the option
X\fI-u\fR does a check-in followed by a check-out without
Xlocking. This option is useful if the file is needed for compilation after the check-in.
XBoth options update the identification markers in the working file
X(see below).
X.PP
XBesides the operations \fIci\fR and \fIco\fR, RCS provides the following
Xcommands:
X\fIident\fR (extract identification markers),
X\fIrcs\fR (change RCS file attributes),
X\fIrcsclean\fR (remove unchanged working files),
X\fIrcsdiff\fR (compare revisions),
X\fIrcsfreeze\fR (record a configuration),
X\fIrcsmerge\fR (merge revisions),
Xand \fIrlog\fR (read log messages and other information in RCS files).
XA synopsis of these commands appears in the Appendix.
X.NH 2
XAutomatic Identification
X.PP
XRCS can stamp source and object code with special identification strings,
Xsimilar to product and serial numbers.
XTo obtain such identification, place the marker
X.D(
X$Header$
X.D)
Xinto the text of a revision, for instance inside a comment.
XThe check-out operation will replace this marker with a string of the form
X.D(
X$Header: filename revisionnumber date time author state locker $
X.D)
XThis string need never be touched, because \fIco\fR keeps it
Xup to date automatically.
XTo propagate the marker into object code, simply put
Xit into a literal character string. In C, this is done as follows:
X.D(
Xstatic char rcsid[] = "$Header$";
X.D)
XThe command \fIident\fR extracts such markers from any file, in particular from
Xobject code.
X\fIIdent\fR helps to find out
Xwhich revisions of which modules were used in a given program.
XIt returns a complete and unambiguous component list,
Xfrom which a copy of the program can be reconstructed.
XThis facility is invaluable for program maintenance.
X.PP
XThere are several additional identification markers, one for each component
Xof $Header$.
XThe marker
X.D(
X$Log$
X.D)
Xhas a similar function. It accumulates
Xthe log messages that are requested during check-in.
XThus, one can maintain the complete history of a revision directly inside it,
Xby enclosing it in a comment.
XFigure 1 is a partial reproduction of a log contained in revision 4.1 of
Xthe file \fIci.c\fR. The log appears at the beginning of the file,
Xand makes it easy to determine what the recent modifications were.
X.sp
X.nr VS 12pts
X.vs 12pts
X.ne 18
X.nf
X.in +0.5i
X/* $Log: ci.c,v $
X * Revision 4.1 83/05/10 17:03:06 wft
X * Added option -d and -w, and updated assignment of date, etc. to new delta.
X * Added handling of default branches.
X *
X * Revision 3.9 83/02/15 15:25:44 wft
X * Added call to fastcopy() to copy remainder of RCS file.
X *
X * Revision 3.8 83/01/14 15:34:05 wft
X * Added ignoring of interrupts while new RCS file is renamed;
X * avoids deletion of RCS files by interrupts.
X *
X * Revision 3.7 82/12/10 16:09:20 wft
X * Corrected checking of return code from diff.
X * An RCS file now inherits its mode during the first ci from the working file,
X * except that write permission is removed.
X */
X.in 0
X.ce 1
XFigure 1. Log entries produced by the marker $Log$.
X.fi
X.nr VS 18pts
X.vs 18pts
X.sp 0
X.LP
XSince revisions are stored in the form of differences,
Xeach log message is
Xphysically stored once,
Xindependent of the number of revisions present.
XThus, the $Log$ marker incurs negligible space overhead.
X.NH
XThe RCS Revision Tree
X.PP
XRCS arranges revisions in an ancestral tree.
XThe \fIci\fR command builds this tree; the auxiliary command \fIrcs\fR
Xprunes it.
XThe tree has a root revision, normally numbered 1.1, and successive revisions
Xare numbered 1.2, 1.3, etc. The first field of a revision number
Xis called the \fIrelease number\fR and the second one
Xthe \fIlevel number\fR. Unless given explicitly,
Xthe \fIci\fR command assigns a new revision number
Xby incrementing the level number of the previous revision.
XThe release number must be incremented explicitly, using the
X\fI-r\fR option of \fIci\fR.
XAssuming there are revisions 1.1, 1.2, and 1.3 in the RCS file f.c,v, the command
X.D(
Xci -r2.1 f.c \fRor\fI ci -r2 f.c
X.D)
Xassigns the number 2.1 to the new revision.
XLater check-ins without the \fI-r\fR option will assign the numbers 2.2, 2.3,
Xand so on.
XThe release number should be incremented only at major transition points
Xin the development, for instance when a new release of a software product has
Xbeen completed.
X.NH 2
XWhen are branches needed?
X.PP
XA young revision tree is slender:
XIt consists of only one branch, called the trunk.
XAs the tree ages, side branches may form.
XBranches are needed in the following 4 situations.
X.IP "\fITemporary fixes\fR"
X.sp 0
XSuppose a tree has 5 revisions grouped in 2 releases,
Xas illustrated in Figure 2.
XRevision 1.3, the last one of release 1, is in operation at customer sites,
Xwhile release 2 is in active development.
X.ne 4
X.PS 4i
X.ps -2
Xbox "1.1"
Xarrow
Xbox "1.2"
Xarrow
Xbox "1.3"
Xarrow
Xbox "2.1"
Xarrow
Xbox "2.2"
Xarrow dashed
X.ps +2
X.PE
X.ce 1
XFigure 2. A slender revision tree.
X.sp 0
XNow imagine a customer requesting a fix of
Xa problem in revision 1.3, although actual development has moved on
Xto release 2. RCS does not permit an extra
Xrevision to be spliced in between 1.3 and 2.1, since that would not reflect
Xthe actual development history. Instead, create a branch
Xat revision 1.3, and check in the fix on that branch.
XThe first branch starting at 1.3 has number 1.3.1, and
Xthe revisions on that branch are numbered 1.3.1.1, 1.3.1.2, etc.
XThe double numbering is needed to allow for another
Xbranch at 1.3, say 1.3.2.
XRevisions on the second branch would be numbered
X1.3.2.1, 1.3.2.2, and so on.
XThe following steps create
Xbranch 1.3.1 and add revision 1.3.1.1:
X.sp 0
X.I
X.nr VS 12pts
X.vs 12pts
X.TS
Xtab(%);
Xl l l.
X %co -r1.3 f.c % -- check out revision 1.3
X %edit f.c % -- change it
X %ci -r1.3.1 f.c % -- check it in on branch 1.3.1
X.TE
X.nr VS 18pts
X.vs 18pts
X.R
XThis sequence of commands transforms the tree of Figure 2 into
Xthe one in Figure 3.
XNote that it may be necessary to incorporate the differences
Xbetween 1.3 and 1.3.1.1
Xinto a revision at level 2. The operation \fIrcsmerge\fR automates this
Xprocess (see the Appendix).
X.ne 7
X.PS 4i
X.ps -2
X box "1.1"
X arrow
X box "1.2"
X arrow
XR13: box "1.3"
X arrow
XR21: box "2.1"
X arrow
XR22: box "2.2"
X arrow dashed
X line invis down from R21.s
XRB1: box "1.3.1.1"
X arrow dashed right from RB1.e
X arrow from R13.s to RB1.w
X.ps +2
X.PE
X.ce 1
XFigure 3. A revision tree with one side branch
X
X.IP "\fIDistributed development and customer modifications\fR"
X.sp 0
XAssume a situation as in Figure 2, where revision 1.3 is in operation
Xat several customer sites,
Xwhile release 2 is in development.
XCustomer sites should use RCS to store the distributed software.
XHowever, customer modifications should not be placed on the same branch
Xas the distributed source; instead, they should be placed on a side branch.
XWhen the next software distribution arrives,
Xit should be appended to the trunk of
Xthe customer's RCS file, and the customer
Xcan then merge the local modifications back into the new release.
XIn the above example, a
Xcustomer's RCS file would contain the following tree, assuming
Xthat the customer has received revision 1.3, added his local modifications
Xas revision 1.3.1.1, then received revision 2.4, and merged
X2.4 and 1.3.1.1, resulting in 2.4.1.1.
X.ne 7
X.PS 4i
X.ps -2
XR13: box "1.3"
X line invis
XR21: box invis
X line invis
XR22: box invis
X line invis
XR24: box "2.4"
X line invis
XR25: box invis
X line invis
X arrow from R13.e to R24.w
X line invis down from R21.s
XRB1: box "1.3.1.1"
X arrow from R13.s to RB1.w
X right
X line invis down from R25.s
XRB2: box "2.4.1.1"
X arrow from R24.s to RB2.w
X.ps +2
X.PE
X.ce 1
XFigure 4. A customer's revision tree with local modifications.
X.sp 1
XThis approach is actually practiced in the CSNET project,
Xwhere several universities and a company cooperate
Xin developing a national computer network.
X.IP "\fIParallel development\fR"
X.sp 0
XSometimes it is desirable to explore an alternate design or
Xa different implementation technique in parallel with the
Xmain line development. Such development
Xshould be carried out on a side branch.
XThe experimental changes may later be moved into the main line, or abandoned.
X.IP "\fIConflicting updates\fR"
X.sp 0
XA common occurrence is that one programmer
Xhas checked out a revision, but cannot complete the assignment
Xfor some reason. In the meantime, another person
Xmust perform another modification
Ximmediately. In that case, the second person should check-out the same revision,
Xmodify it, and check it in on a side branch, for later merging.
X.PP
XEvery node in a revision tree consists of the following attributes:
Xa revision number, a check-in date and time, the author's identification,
Xa log entry, a state and the actual text. All these attributes
Xare determined at the time the revision is checked in.
XThe state attribute indicates the status of a revision.
XIt is set automatically to `experimental' during check-in.
XA revision can later be promoted to a higher status, for example
X`stable' or `released'. The set of states is user-defined.
X.NH 2
XRevisions are represented as deltas
X.PP
XFor conserving space, RCS stores revisions in the form
Xof deltas, i.e., as differences between revisions.
XThe user interface completely hides this fact.
X.PP
XA delta is a sequence of edit commands that transforms one string
Xinto another. The deltas employed by RCS are line-based, which means
Xthat the only edit commands allowed are insertion and deletion of lines.
XIf a single character in a line is changed, the
Xedit scripts consider the entire line changed.
XThe program \fIdiff\fR\u2\d
Xproduces a small, line-based delta between pairs of text files.
XA character-based edit script would take much longer to compute,
Xand would not be significantly shorter.
X.PP
XUsing deltas is a classical space-time tradeoff: deltas reduce the
Xspace consumed, but increase access time.
XHowever, a version control tool should impose as little delay
Xas possible on programmers.
XExcessive delays discourage the use of version controls,
Xor induce programmers to take shortcuts that compromise system integrity.
XTo gain reasonably fast access time for both editing and compiling,
XRCS arranges deltas in the following way.
XThe most recent revision on the trunk is stored intact.
XAll other revisions on the trunk are stored as reverse deltas.
XA reverse delta describes how to go backward in the development history:
Xit produces the desired revision if applied to the successor of that revision.
XThis implementation has the advantage
Xthat extraction of the latest revision is a simple and fast copy
Xoperation.
XAdding a new revision to the trunk is also fast: \fIci\fR simply
Xadds the new revision intact, replaces the previous
Xrevision with a reverse delta, and keeps the rest of the old deltas.
XThus, \fIci\fR requires the computation
Xof only one new delta.
X.PP
XBranches need special treatment. The naive solution would be to
Xstore complete copies for the tips of all branches.
XClearly, this approach would cost too much space. Instead,
XRCS uses \fIforward\fR deltas for branches. Regenerating a revision
Xon a side branch proceeds as follows. First, extract the latest revision
Xon the trunk; secondly, apply reverse deltas until the fork revision for
Xthe branch is obtained; thirdly, apply forward deltas until the desired
Xbranch revision is reached. Figure 5 illustrates a tree with
Xone side branch. Triangles pointing to the left and right represent
Xreverse and forward deltas, respectively.
X.ne 8
X.PS 4i
X.ps -2
Xdefine BD X [line invis $1 right .5;
Xline up .3 then left .5 down .3 then right .5 down .3 then up .3] X
X
Xdefine FD X [line invis $1 right .5;
Xline left .5 down .3 then up .6 then right .5 down .3;] X
X
Xright
XD11: BD(" 1.1")
X arrow right from D11.e
XD12: BD(" 1.2")
X arrow right from D12.e
XD13: BD(" 1.3")
X arrow right from D13.e
XD21: BD(" 2.1")
X arrow right from D21.e
XD22: box "2.2"
X line invis down from D21.s
XF1: FD("1.3.1.1 ")
X arrow from D13.se to F1.w
X arrow from F1.e right
X right
XF2: FD("1.3.1.2 ")
X.ps +2
X.PE
X.ce 1
XFigure 5. A revision tree with reverse and forward deltas.
X.sp 0
X.PP
XAlthough implementing fast check-out for the latest trunk revision,
Xthis arrangement has the disadvantage that generation of other revisions
Xtakes time proportional to the number of deltas applied. For example,
Xregenerating the branch tip in Figure 5 requires application of five
Xdeltas (including the initial one). Since usage statistics show that
Xthe latest trunk revision is the one that is retrieved in 95 per cent
Xof all cases (see the section on usage statistics), biasing check-out time
Xin favor of that revision results in significant savings.
XHowever, careful implementation of the delta application process is
Xnecessary to provide low retrieval overhead for other revisions, in
Xparticular for branch tips.
X.PP
XThere are several techniques for delta application.
XThe naive one is to pass each delta to a general-purpose text editor.
XA prototype of RCS invoked the UNIX editor \fIed\fR both
Xfor applying deltas and for expanding the identification markers.
XAlthough easy to implement, performance was poor, owing to the
Xhigh start-up costs and excess generality of \fIed\fR. An intermediate
Xversion of RCS used a special-purpose, stream-oriented editor.
XThis technique reduced the cost of applying a delta to the cost of
Xchecking out the latest trunk revision. The reason for this behavior
Xis that each delta application involves a complete pass over
Xthe preceding revision.
X.PP
XHowever, there is a much better algorithm. Note that the deltas are
Xline oriented and that most of the work of a stream editor involves
Xcopying unchanged lines from one revision to the next. A faster
Xalgorithm avoids unnecessary copying of character strings by using
Xa \fIpiece table\fR.
XA piece table is a one-dimensional array, specifying how a given
Xrevision is `pieced together' from lines in the RCS file.
XSuppose piece table \fIPT\dr\u\fR represents revision \fIr\fR.
XThen \fIPT\dr\u[i]\fR contains the starting position of line \fIi\fR
Xof revision \fIr\fR.
XApplication of the next delta transforms piece table \fIPT\dr\u\fR
Xinto \fIPT\dr+1\u\fR. For instance, a delete command removes a
Xseries of entries from the piece table. An insertion command inserts
Xnew entries, moving the entries following the insertion point further down the
Xarray. The inserted entries point to the text lines in the delta.
XThus, no I/O is involved except for reading the delta itself. When all
Xdeltas have been applied to the piece table, a sequential pass
Xthrough the table looks up each line in the RCS file and copies it to
Xthe output file, updating identification markers at the same time.
XOf course, the RCS file must permit random access, since the copied
Xlines are scattered throughout that file. Figure 6 illustrates an
XRCS file with two revisions and the corresponding piece tables.
X.ne 13
X.sp 12
X.ce 1
XFigure 6. An RCS file and its piece tables
X.sp 0
X.PP
XThe piece table approach has the property that the time for applying a single
Xdelta is roughly determined by the size of the delta, and not by the
Xsize of the revision. For example, if a delta is
X10 per cent of the size of a revision, then applying it takes only
X10 per cent of the time to generate the latest trunk revision. (The stream
Xeditor would take 100 per cent.)
X.PP
XThere is an important alternative for representing deltas that affects
Xperformance. SCCS\u3\d,
Xa precursor of RCS, uses \fIinterleaved\fR deltas.
XA file containing interleaved deltas is partitioned into blocks of lines.
XEach block has a header that specifies to which revision(s) the block
Xbelongs. The blocks are sorted out in such a way that a single
Xpass over the file can pick up all the lines belonging to a given
Xrevision. Thus, the regeneration time for all revisions is the same:
Xall headers must be inspected, and the associated blocks either copied
Xor skipped. As the number of revisions increases, the cost of retrieving
Xany revision is much higher than the cost of checking out the
Xlatest trunk revision with reverse deltas. A detailed comparison
Xof SCCS's interleaved deltas and RCS's reverse deltas can be found
Xin Reference 4.
XThis reference considers the version of RCS with the
Xstream editor only. The piece table method improves performance
Xfurther, so that RCS is always faster than SCCS, except if 10
Xor more deltas are applied.
X.PP
XAdditional speed-up for both delta methods can be obtained by caching
Xthe most recently generated revision, as has been implemented in DSEE.\u5\d
XWith caching, access time to frequently used revisions can approach normal file
Xaccess time, at the cost of some additional space.
X.NH
XLocking: A Controversial Issue
X.PP
XThe locking mechanism for RCS was difficult to design.
XThe problem and its solution are first presented in their `pure' form,
Xfollowed by a discussion of the complications
Xcaused by `real-world' considerations.
X.PP
XRCS must prevent two or more persons from depositing competing changes of the
Xsame revision.
XSuppose two programmers check out revision 2.4 and
Xmodify it. Programmer A checks in a revision before programmer B.
XUnfortunately, programmer B has not seen A's
Xchanges, so the effect is that A's changes are covered up by B's deposit.
XA's changes are not lost since all revisions
Xare saved, but they are confined to a single revision\(dd.
X.FS
X\(dd Note that this problem is entirely different from the atomicity problem.
XAtomicity means that
Xconcurrent update operations on the same RCS file cannot be permitted,
Xbecause that may result in inconsistent data.
XAtomic updates are essential (and implemented in RCS),
Xbut do not solve the conflict discussed here.
X.FE
X.PP
XThis conflict is prevented in RCS by locking.
XWhenever someone intends to edit a revision (as opposed
Xto reading or compiling it), the revision should be checked out
Xand locked,
Xusing the \fI-l\fR option on \fIco\fR. On subsequent check-in,
X\fIci\fR tests the lock and then removes it.
XAt most one programmer at a time may
Xlock a particular revision, and only this programmer may check in
Xthe succeeding revision.
XThus, while a revision is locked, it is the exclusive responsibility
Xof the locker.
X.PP
XAn important maxim for software tools like RCS is that they must
Xnot stand in the way of making progress with a project.
XThis consideration leads to several weakenings of the locking mechanism.
XFirst of all, even if a revision is locked, it can
Xstill be checked out. This is necessary if other people
Xwish to compile or inspect the locked revision
Xwhile the next one is in preparation. The only operations they
Xcannot do are to lock the revision or to check in the succeeding one. Secondly,
Xcheck-in operations on other branches in the RCS file are still possible; the
Xlocking of one revision does not affect any other revision.
XThirdly, revisions are occasionally locked for a long period of time
Xbecause a programmer is absent or otherwise unable to complete
Xthe assignment. If another programmer has to make a pressing change,
Xthere are the following three alternatives for making progress:
Xa) find out who is holding the lock and ask that person to release it;
Xb) check out the locked revision, modify it, check it
Xin on a branch, and merge the changes later;
Xc) break the lock. Breaking a lock leaves a highly visible
Xtrace, namely an electronic mail message that is sent automatically to the
Xholder of the lock, recording the breaker and a commentary requested from him.
XThus, breaking locks is tolerated under certain circumstances,
Xbut will not go unnoticed.
XExperience has shown that the automatic mail message attaches a high enough
Xstigma to lock breaking,
Xsuch that programmers break locks only in real emergencies,
Xor when a co-worker resigns and leaves locked revisions behind.
X.PP
XIf an RCS file is private, i.e., when a programmer owns an RCS file
Xand does not expect anyone else to perform check-in operations,
Xlocking is an unnecessary nuisance.
XIn this case,
Xthe `strict locking feature' discussed earlier may be disabled,
Xprovided that file protection
Xis set such that only the owner may write the RCS file.
XThis has the effect that only the owner can check-in revisions,
Xand that no lock is needed for doing so.
X.PP
XAs added protection,
Xeach RCS file contains an access list that specifies the users
Xwho may execute update operations. If an access list is empty,
Xonly normal UNIX file protection applies. Thus, the access list is
Xuseful for restricting the set of people who would otherwise have update
Xpermission. Just as with locking, the access list
Xhas no effect on read-only operations such as \fIco\fR. This approach
Xis consistent with the UNIX philosophy of openness, which contributes
Xto a productive software development environment.
X.NH
XConfiguration Management
X.PP
XThe preceding sections described how RCS deals with revisions of individual
Xcomponents; this section discusses how to handle configurations.
XA configuration is a set of revisions, where each revision comes
Xfrom a different revision group, and the revisions are selected
Xaccording to a certain criterion.
XFor example,
Xin order to build a functioning compiler, the `right'
Xrevisions from the scanner, the parser, the optimizer
Xand the code generator must be combined.
XRCS, in conjunction with MAKE,
Xprovides a number of facilities to effect a smooth selection.
X.NH 2
XRCS Selection Functions
X.PP
X.IP "\fIDefault selection\fR"
X.sp 0
XDuring development, the usual selection criterion is to choose
Xthe latest revision of all components. The \fIco\fR command
Xmakes this selection by default. For example, the command
X.D(
Xco *,v
X.D)
Xretrieves the latest revision on the default branch of each RCS file
Xin the current directory.
XThe default branch is usually the trunk, but may be
Xset to be a side branch.
XSide branches as defaults are needed in distributed software development,
Xas discussed in the section on the RCS revision tree.
X
X.IP "\fIRelease based selection\fR"
X.sp 0
XSpecifying a release or branch number selects the latest revision in
Xthat release or branch.
XFor instance,
X.D(
Xco -r2 *,v
X.D)
Xretrieves the latest revision with release number 2 from each RCS file.
XThis selection is convenient if a release has been completed and
Xdevelopment has moved on to the next release.
X
X.IP "\fIState and author based selection\fR"
X.sp 0
XIf the highest level number within a given release number
Xis not the desired one,
Xthe state attribute can help. For example,
X.D(
Xco -r2 -sReleased *,v
X.D)
Xretrieves the latest revision with release number 2 whose state attribute
Xis `Released'.
XOf course, the state attribute has to be set appropriately, using the
X\fIci\fR or \fIrcs\fR commands.
XAnother alternative is to select a revision by its author,
Xusing the \fI-w\fR option.
X
X.IP "\fIDate based selection\fR"
X.sp 0
XRevisions may also be selected by date.
XSuppose a release of an entire system was
Xcompleted and current on March 4, at 1:00 p.m. Then the command
X.D(
Xco -d"March 4, 1:00 pm" *,v
X.D)
Xchecks out all the components of that release, independent of the numbering.
XThe \fI-d\fR option specifies a `cutoff date', i.e.,
Xthe revision selected has a check-in date that
Xis closest to, but not after the date given.
X208z
X.IP "\fIName based selection\fR"
X.sp 0
XThe most powerful selection function is based on assigning symbolic
Xnames to revisions and branches.
XIn large systems, a single release number or date is not sufficient
Xto collect the appropriate revisions from all groups.
XFor example, suppose one wishes to combine release 2
Xof one subsystem and release 15 of another.
XMost likely, the creation dates of those releases differ also.
XThus, a single revision number or date passed to the \fIco\fR command
Xwill not suffice to select the right revisions.
XSymbolic revision numbers solve this problem.
XEach RCS file may contain a set of symbolic names that are mapped
Xto numeric revision numbers. For example, assume
Xthe symbol \fIV3\fR is bound to release number 2 in file \fIs,v\fR, and to
Xrevision number 15.9 in \fIt,v\fR.
XThen the single command
X.D(
Xco -rV3 s,v t,v
X.D)
Xretrieves the latest revision of release 2 from \fIs,v\fR,
Xand revision 15.9 from \fIt,v\fR.
XIn a large system with many modules, checking out all
Xrevisions with one command greatly simplifies configuration management.
X.PP
XJudicious use of symbolic revision numbers helps with organizing
Xlarge configurations.
XA special command, \fIrcsfreeze\fR,
Xassigns a symbolic revision number to a selected revision
Xin every RCS file.
X\fIRcsfreeze\fR effectively freezes a configuration.
XThe assigned symbolic revision number selects all components
Xof the configuration.
XIf necessary, symbolic numbers
Xmay even be intermixed with numeric ones. Thus, \fIV3.5\fR in the
Xabove example
Xwould select revision 2.5 in \fIs,v\fR and branch 15.9.5 in \fIt,v\fR.
X.PP
XThe options \fI-r\fR, \fI-s\fR, \fI-w\fR and \fI-d\fR
Xmay be combined. If a branch is given, the latest revision
Xon that branch satisfying all conditions is retrieved;
Xotherwise, the default branch is used.
X.NH 2
XCombining MAKE and RCS
X.PP
XMAKE\u1\d
Xis a program that processes configurations.
XIt is driven by configuration specifications
Xrecorded in a special file, called a `Makefile'.
XMAKE avoids redundant processing steps
Xby comparing creation dates of source and processed objects.
XFor example, when instructed to compile all
Xmodules of a given system, it only recompiles
Xthose source modules that were changed
Xsince they were processed last.
X.PP
XMAKE has been extended with an auto-checkout feature for RCS.
XWhen a certain file to be processed is not present,
XMAKE attempts a check-out operation.
XIf successful, MAKE performs the required processing, and then deletes
Xthe checked out file to conserve space.
XThe selection parameters discussed above can be passed to MAKE
Xeither as parameters, or directly embedded in the Makefile.
XMAKE has also been extended to search the subdirectory named \fIRCS\fR
Xfor needed files, rather than just the current working directory.
XHowever, if a working file is present, MAKE totally ignores the corresponding
XRCS file and uses the working file.
X(In newer versions of MAKE distributed by AT&T and others,
Xauto-checkout can be
Xachieved with the rule DEFAULT, instead of a special extension of MAKE.
XHowever, a file checked out by the rule DEFAULT
Xwill not be deleted after processing. \fIRcsclean\fR can be
Xused for that purpose.)
X.PP
XWith auto-checkout, RCS/MAKE can effect a selection rule
Xespecially tuned for multi-person software development and maintenance.
XIn these situations,
Xprogrammers should obtain configurations that consist of
Xthe revisions they have personally checked out plus the latest
Xchecked in revision of all other revision groups.
XThis schema can be set up as follows.
X.PP
XEach programmer chooses a working directory
Xand places into it a symbolic link, named \fIRCS\fR,
Xto the directory containing the relevant RCS files.
XThe symbolic link makes sure that \fIco\fR and \fIci\fR
Xoperations need only specify the working files, and that
Xthe Makefile need not be changed.
XThe programmer then checks out the needed files and modifies them.
XIf MAKE is invoked,
Xit composes configurations by selecting those
Xrevisions that are checked out, and the rest from the
Xsubdirectory \fIRCS\fR.
XThe latter selection may be controlled by a symbolic
Xrevision number or any of the other selection criteria.
XIf there are several programmers editing in separate working directories,
Xthey are insulated from each other's changes until checking in their
Xmodifications.
X.PP
XSimilarly, a maintainer can recreate an older configuration
Xby starting to work in an empty working directory.
XDuring the initial MAKE invocation, all revisions are selected from RCS files.
XAs the maintainer checks out files and modifies them,
Xa new configuration is gradually built up.
XEvery time MAKE is invoked, it substitutes the modified revisions
Xinto the configuration being manipulated.
X.PP
XA final application of RCS is to use it for storing Makefiles.
XRevision groups of Makefiles represent
Xmultiple versions of configurations.
XWhenever a configuration is baselined or distributed,
Xthe best approach is to unambiguously fix
Xthe configuration with a symbolic revision number by calling
X\fIrcsfreeze\fR,
Xto embed that symbol into the Makefile, and to
Xcheck in the Makefile (using the same symbolic revision number).
XWith this approach, old configurations
Xcan be regenerated easily and reliably.
X.NH
XUsage Statistics
X.PP
XThe following usage statistics were collected on two DEC VAX-11/780
Xcomputers of the Purdue Computer Science Department. Both machines
Xare mainly used for research purposes. Thus, the data
Xreflect an environment in which the majority of projects
Xinvolve prototyping and advanced software development,
Xbut relatively little long-term maintenance.
X.PP
XFor the first experiment,
Xthe \fIci\fR and \fIco\fR operations were instrumented
Xto log the number of backward and forward deltas applied.
XThe data were collected during a 13 month period
Xfrom Dec. 1982 to Dec. 1983.
XTable I summarizes the results.
X.sp 0
X.nr VS 12pts
X.vs 12pts
X.TS
Xcenter,box,tab(#);
Xc|c|c|c|c s|c s
Xc|c|c|c|c s|c s
Xl|n|n|n|n n|n n.
XOperation#Total#Total deltas#Mean deltas#Operations#Branch
X #operations #applied#applied#with >1 delta#operations
X_
Xco # 7867# 9320#1.18#509#(6%)#203#(3%)
Xci # 3468# 2207#0.64# 85#(2%)# 75#(2%)
Xci & co#11335#11527#1.02#594#(5%)#278#(2%)
X.TE
X.ce 1
XTable I. Statistics for \fIco\fR and \fIci\fR operations.
X.nr VS 18pts
X.vs 18pts
X.PP
XThe first two lines show statistics for check-out and check-in;
Xthe third line shows the combination.
XRecall that \fIci\fR performs an implicit check-out to obtain
Xa revision for computing the delta.
XIn all measures presented, the most recent revision (stored intact)
Xcounts as one delta. The number of deltas applied represents
Xthe number of passes necessary, where the first `pass' is a copying step.
X.PP
XNote that the check-out operation is executed more than
Xtwice as frequently as the check-in operation.
XThe fourth column gives the mean number of deltas
Xapplied in all three cases.
XFor \fIci\fR, the mean number of deltas applied is less
Xthan one.
XThe reasons are that the initial check-in requires no delta at all, and that
Xthe only time \fIci\fR requires more than one delta is for branches.
XColumn 5 shows the actual number of operations that applied more than one
Xdelta.
XThe last column indicates that branches were not used often.
X.PP
XThe last three columns demonstrate that the most recent trunk revision
Xis by far the most frequently accessed.
XFor RCS, check-out of
Xthis revision is a simple copy operation, which is the absolute minimum
Xgiven the copy-semantics of \fIco\fR.
XAccess to older revisions and branches
Xis more common in non-academic environments,
Xyet even if access to older deltas were an order
Xof magnitude more frequent,
Xthe combined average number of deltas applied would still be below 1.2.
XSince RCS is faster than SCCS until up to 10 delta applications,
Xreverse deltas are clearly the method of choice.
X.PP
XThe second experiment, conducted in March of 1984,
Xinvolved surveying the existing RCS files
Xon our two machines. The goal was to determine the mean number of
Xrevisions per RCS file, as well as the space consumed by them.
XTable II shows the results. (Tables I and II were produced at different
Xtimes and are unrelated.)
X.sp 0
X.nr VS 12pts
X.vs 12pts
X.TS
Xcenter,box,tab(#);
Xc | c | c | c | c | c | c
Xc | c | c | c | c | c | c
Xl | n | n | n | n | n | n
X.
X #Total RCS#Total#Mean#Mean size of#Mean size of#Overhead
X #files#revisions#revisions#RCS files#revisions
X_
XAll files #8033#11133#1.39#6156#5585#1.10
XFiles with#1477# 4578#3.10#8074#6041#1.34
X\(>= 2 deltas
X.TE
X.ce 1
XTable II. Statistics for RCS files.
X.nr VS 18pts
X.vs 18pts
X.PP
XThe mean number of revisions per RCS file is 1.39.
XColumns 5 and 6 show the mean sizes (in bytes) of an RCS file
Xand of the latest revision of each RCS file, respectively.
XThe `overhead' column contains the ratio of the mean sizes.
XAssuming that all revisions in an RCS file are approximately the same size,
Xthis ratio gives a measure of the space consumed by the extra revisions.
X.PP
XIn our sample, over 80 per cent of the RCS files contained only a single revision.
XThe reason is that our
Xsystems programmers routinely check in all source files
Xon the distribution tapes, even though they may never touch them again.
XTo get a better indication of how much space savings are possible
Xwith deltas, all measures with those files
Xthat contained 2 or more revisions were recomputed. Only for those files
Xis RCS necessary.
XAs shown in the second line, the average number of revisions for those files is
X3.10, with an overhead of 1.34. This means that the extra 2.10 deltas
Xrequire 34 per cent extra space, or
X16 per cent per extra revision.
XRochkind\u3\d
Xmeasured the space consumed by SCCS, and
Xreported an average of 5 revisions per group
Xand an overhead of 1.37 (or about 9 per cent per extra revision).
XIn a later paper, Glasser\u6\d
Xobserved an average of 7 revisions per group in a single, large project,
Xbut provided no overhead figure.
XIn his paper on DSEE\u5\d,
XLeblang reported that delta storage combined with blank compression
Xresults in an overhead of a mere 1\-2 per cent per revision.
XSince leading blanks accounted for about 20 per cent of the surveyed Pascal
Xprograms, a revision group with 5\-10 members was smaller
Xthan a single cleartext copy.
X.PP
XThe above observations demonstrate clearly that the space needed
Xfor extra revisions is small. With delta storage, the luxury of
Xkeeping multiple revisions online is certainly affordable.
XIn fact, introducing a system with delta storage may reduce
Xstorage requirements, because programmers often save back-up copies
Xanyway. Since back-up copies are stored much more efficiently with deltas,
Xintroducing a system such as RCS may
Xactually free a considerable amount of space.
X.NH
XSurvey of Version Control Tools
X.PP
XThe need to keep back-up copies of software arose when
Xprograms and data were no longer stored on paper media, but were entered
Xfrom terminals and stored on disk.
XBack-up copies are desirable for reliability, and many modern editors
Xautomatically save a back-up copy for every file touched.
XThis strategy
Xis valuable for short-term back-ups, but not suitable for long-term
Xversion control, since an existing back-up copy is overwritten whenever the
Xcorresponding file is edited.
X.PP
XTape archives are suitable for long-term, offline storage.
XIf all changed files are dumped on a back-up tape once per day, old revisions
Xremain accessible. However, tape archives are unsatisfactory
Xfor version control in several ways. First, backing up the file
Xsystem every 24 hours does not capture intermediate revisions.
XSecondly, the old revisions are not online,
Xand accessing them is tedious and time-consuming.
XIn particular, it is impractical to
Xcompare several old revisions of a group,
Xbecause that may require mounting and searching several tapes.
XTape archives are important fail-safe tools in the
Xevent of catastrophic disk failures or accidental deletions,
Xbut they are ill-suited for version control.
XConversely, version control tools do not obviate the
Xneed for tape archives.
X.PP
XA natural technique for keeping several old revisions online is
Xto never delete a file.
XEditing a file
Xsimply creates a new file with the same
Xname, but with a different sequence number.
XThis technique, available as an option in DEC's VMS operating system,
Xturns out to be inadequate for version control.
XFirst, it is prohibitively expensive in terms of storage costs,
Xespecially since no data compression techniques are employed.
XSecondly, indiscriminately storing every change produces too many
Xrevisions, and programmers have difficulties distinguishing them.
XThe proliferation of revisions forces programmers to spend much time on
Xfinding and deleting useless files.
XThirdly, most of the support functions like locking, logging,
Xrevision selection,
Xand identification described in this paper are not available.
X.PP
XAn alternative approach is to separate editing from revision control.
XThe user may repeatedly edit a given revision,
Xuntil freezing it with an explicit command.
XOnce a revision is frozen, it is stored permanently and can no longer be modified.
X(In RCS, freezing a revisions is done with \fIci\fR.)
XEditing a frozen revision implicitly creates a new one, which
Xcan again be changed repeatedly until it is frozen itself.
XThis approach saves exactly those revisions that the user
Xconsiders important, and keeps the number of revisions manageable.
XIBM's CLEAR/CASTER\u7\d,
XAT&T's SCCS\u3\d,
XCMU's SDC\u8\d
Xand DEC's CMS\u9\d,
Xare examples of version control systems using this approach.
XCLEAR/CASTER maintains a data base of programs, specifications,
Xdocumentation and messages, using deltas.
XIts goal is to provide control over the development process from a
Xmanagement viewpoint.
XSCCS stores multiple revisions of source text in an ancestral tree,
Xrecords a log entry for each revision,
Xprovides access control, and has facilities
Xfor uniquely identifying each revision.
XAn efficient delta technique
Xreduces the space consumed by each revision group.
XSDC is much simpler than SCCS because it stores not more than
Xtwo revisions. However, it maintains a complete log for all old
Xrevisions, some of which may be on back-up tape.
XCMS, like SCCS, manages tree-structured revision groups,
Xbut offers no identification mechanism.
X.PP
XTools for dealing with configurations are still in a state of flux.
XSCCS, SDC and CMS can be combined with MAKE or MAKE-like programs.
XSince flexible selection rules are missing from all these tools,
Xit is sometimes difficult
Xto specify precisely which revision of each group
Xshould be passed to MAKE for building a desired configuration.
XThe Xerox Cedar system\u10\d
Xprovides a `System Modeller' that can rebuild
Xa configuration from an arbitrary set of module revisions.
XThe revisions of a module are only distinguished by creation time,
Xand there is no tool for managing groups.
XSince the selection rules are primitive,
Xthe System Modeller appears to be somewhat tedious to use.
XApollo's DSEE\u5\d
Xis a sophisticated software engineering environment.
XIt manages revision groups in a way similar to SCCS and CMS. Configurations
Xare built using `configuration threads'.
XA configuration thread states which revision of each group
Xnamed in a configuration should be chosen.
XA configuration thread may contain dynamic specifiers
X(e.g., `choose the revisions I am currently working on,
Xand the most recent revisions otherwise'), which are bound
Xautomatically at build time.
XIt also provides a notification mechanism for alerting
Xmaintainers about the need to rebuild a system after a change.
X.PP
XRCS is based on a general model for describing
Xmulti-version/multi-configuration systems\u11\d.
XThe model describes systems using AND/OR graphs, where AND nodes represent
Xconfigurations, and OR nodes represent version groups.
XThe model gives rise to a suit of selection rules for
Xcomposing configurations, almost all of which are implemented in RCS.
XThe revisions selected by RCS are passed to MAKE for configuration building.
XRevision group management is modelled after SCCS.
XRCS retains SCCS's best features,
Xbut offers a significantly simpler user interface,
Xflexible selection rules, adequate integration with MAKE
Xand improved identification.
XA detailed comparison of RCS and SCCS appears in Reference 4.
X.PP
XAn important component of all revision control systems
Xis a program for computing deltas.
XSCCS and RCS use the program \fIdiff\fR\u2\d,
Xwhich first computes the longest common substring of two
Xrevisions, and then produces the delta from that substring.
XThe delta is simply an edit script consisting of deletion and
Xinsertion commands that generate one revision from the other.
X.PP
XA delta based on a longest common substring is not necessarily minimal,
Xbecause it does not take advantage of crossing block moves.
XCrossing block moves arise if two or more blocks of lines
X(e.g., procedures)
Xappear in a different order in two revisions.
XAn edit script derived from a longest common substring
Xfirst deletes the shorter of the two blocks, and then reinserts it.
XHeckel\u12\d
Xproposed an algorithm for detecting block moves, but
Xsince the algorithm is based on heuristics,
Xthere are conditions
Xunder which the generated delta is far from minimal.
XDSEE uses this algorithm combined with blank compression,
Xapparently with satisfactory overall results.
XA new algorithm that is guaranteed to produce a minimal delta based on
Xblock moves appears in Reference 13.
XA future release of RCS will use this algorithm.
X.PP
X\fIAcknowledgements\fR:
XMany people have helped make RCS a success by contributed criticisms, suggestions,
Xcorrections, and even whole new commands (including manual pages).
XThe list of people is too long to be
Xreproduced here, but my sincere thanks for their help and
Xgoodwill goes to all of them.
X
X.nr VS 12 pts
X.vs 12pts
X.SH
XAppendix: Synopsis of RCS Operations
X.LP
X.IP "\fIci \fB\- check in revisions\fR"
X.sp 0
X\fICi\fR stores the contents of a working file into the
Xcorresponding RCS file as a new revision.
XIf the RCS file doesn't exist, \fIci\fR creates it.
X\fICi\fR removes the working file, unless one of the options
X\fI-u\fR or \fI-l\fR is present.
XFor each check-in, \fIci\fR asks for a commentary
Xdescribing the changes relative to the previous revision.
X.sp 1
X\fICi\fR assigns the revision number given by the \fI-r\fR option;
Xif that option is missing, it derives the number from the
Xlock held by the user; if there is no lock and locking is not strict,
X\fIci\fR increments the number of the latest revision on the trunk.
XA side branch can only be started by explicitly specifying its
Xnumber with the \fI-r\fR option during check-in.
X.sp 1
X\fICi\fR also determines
Xwhether the revision to be checked in is different from the
Xprevious one, and asks whether to proceed if not.
XThis facility simplifies check-in operations for large systems,
Xbecause one need not remember which files were changed.
X.sp 1
XThe option \fI-k\fR searches the checked in file for identification
Xmarkers containing
Xthe attributes
Xrevision number, check-in date, author and state, and assigns these
Xto the new revision rather than computing them. This option is
Xuseful for software distribution: Recipients of distributed software
Xusing RCS should check in updates with the \fI-k\fR option.
XThis convention guarantees that revision numbers, check-in dates,
Xetc., are the same at all sites.
X.IP "\fIco \fB\- check out revisions\fR"
X.sp 0
X\fICo\fR retrieves revisions according to revision number,
Xdate, author and state attributes. It either places the revision
Xinto the working file, or prints it on the std. output.
X\fICo\fR always expands the identification markers.
X.IP "\fIident \fB\- extract identification markers\fR"
X.sp 0
X\fIIdent\fR extracts the identification markers expanded by \fIco\fR
Xfrom any file and prints them.
X.IP "\fIrcs \fB\- change RCS file attributes\fR"
X.sp 0
X\fIRcs\fR is an administrative operation that changes access lists,
Xlocks, unlocks, breaks locks, toggles the strict-locking feature,
Xsets state attributes and symbolic revision numbers, changes the
Xdescription, and deletes revisions. A revision can
Xonly be deleted if it is not the fork of a side branch.
X.IP "\fIrcsclean \fB\- clean working directory\fR"
X.sp 0
X\fIRcsclean\fR removes working files that were checked out but never changed.
X.IP "\fIrcsdiff \fB\- compare revisions\fR"
X.sp 0
X\fIRcsdiff\fR compares two revisions and prints their
Xdifference, using the UNIX tool \fIdiff\fR.
XOne of the revisions compared may be checked out.
XThis command is useful for finding out about changes.
X.IP "\fIrcsfreeze \fB\- freeze a configuration\fR"
X.sp 0
X\fIRcsfreeze\fR assigns the same symbolic revision number
Xto a given revision in all RCS files.
XThis command is useful for accurately recording a configuration.
X.IP "\fIrcsmerge \fB\- merge revisions\fR"
X.sp 0
X\fIRcsmerge\fR merges two revisions, \fIrev1\fR and \fIrev2\fR,
Xwith respect to a common ancestor.
XA 3-way file comparison determines the segments of lines that
Xare (a) the same in all three revisions, or (b) the same in 2 revisions,
Xor (c) different in all three. For all segments of type (b) where
X\fIrev1\fR is the differing revision,
Xthe segment in \fIrev1\fR replaces the corresponding segment of \fIrev2\fR.
XType (c) indicates an overlapping change, is flagged as an error, and requires user
Xintervention to select the correct alternative.
X.IP "\fIrlog \fB\- read log messages\fR"
X.sp 0
X\fIRlog\fR prints the log messages and other information in an RCS file.
X.bp
X.LP
X.nr VS 12 pts
X.vs 12pts
X.]<
X.ds [F 1
X.]-
X.ds [K FELD02
X.ds [K MakeArticle
X.ds [A Feldman, Stuart I.
X.ds [D March 1979
X.ds [T Make - A Program for Maintaining Computer Programs
X.ds [J Software -- Practice and Experience
X.ds [V 9
X.ds [N 3
X.ds [P 255-265
X.nr [P 1
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 1 journal-article
X.ds [F 2
X.]-
X.ds [K HUNT01
X.ds [T An Algorithm for Differential File Comparison
X.ds [A Hunt, James W.
X.as [A " and McIlroy, M. D.
X.ds [I Computing Science Technical Report, Bell Laboratories
X.ds [R 41
X.ds [D June 1976
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 4 tech-report
X.ds [F 3
X.]-
X.ds [K SCCS
X.ds [A Rochkind, Marc J.
X.ds [D Dec. 1975
X.ds [T The Source Code Control System
X.ds [J IEEE Transactions on Software Engineering
X.ds [V SE-1
X.ds [N 4
X.ds [P 364-370
X.nr [P 1
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 1 journal-article
X.ds [F 4
X.]-
X.ds [K TICH08
X.ds [T Design, Implementation, and Evaluation of a Revision Control System
X.ds [A Tichy, Walter F.
X.ds [B Proceedings of the 6th International Conference on Software Engineering
X.ds [I ACM, IEEE, IPS, NBS
X.ds [D September 1982
X.ds [P 58-67
X.nr [P 1
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 3 article-in-book
X.ds [F 5
X.]-
X.ds [K LEBL01
X.ds [A Leblang, David B.
X.as [A " and Chase, Robert P.
X.ds [T Computer-Aided Software Engineering in a Distributed Workstation Environment
X.ds [O Proceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium
X.as [O " on Practical Software Development Environments.
X.ds [J SIGPLAN Notices
X.ds [V 19
X.ds [N 5
X.ds [D May 1984
X.ds [P 104-112
X.nr [P 1
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 1 journal-article
X.ds [F 1
X.ds [F 3
X.ds [F 6
X.]-
X.ds [K SCCSEval
X.ds [A Glasser, Alan L.
X.ds [D Nov. 1978
X.ds [T The Evolution of a Source Code Control System
X.ds [J Software Engineering Notes
X.ds [V 3
X.ds [N 5
X.ds [P 122-125
X.nr [P 1
X.ds [O Proceedings of the Software Quality and Assurance Workshop.
X.nr [T 0
X.nr [A 1
X.nr [O 1
X.][ 1 journal-article
X.ds [F 5
X.ds [F 7
X.]-
X.ds [K IBMClearCaster
X.ds [A Brown, H.B.
X.ds [D 1970
X.ds [T The Clear/Caster System
X.ds [J Nato Conference on Software Engineering, Rome
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 1 journal-article
X.ds [F 3
X.ds [F 8
X.]-
X.ds [K HabermannSDC
X.ds [A Habermann, A. Nico
X.ds [D Jan. 1979
X.ds [T A Software Development Control System
X.ds [I Technical Report, Carnegie-Mellon University, Department of Computer Science
X.nr [T 0
X.nr [A 0
X.nr [O 0
X.][ 2 book
X.ds [F 9
X.]-
X.ds [K CMS
X.ds [A DEC,
X.ds [T Code Management System
X.ds [I Digital Equipment Corporation
X.ds [O Document No. EA-23134-82
X.ds [D 1982
X.nr [T 0
X.nr [A 0
X.nr [O 0
X.][ 2 book
X.ds [F 10
X.]-
X.ds [K LAMP01
X.ds [A Lampson, Butler W.
X.as [A " and Schmidt, Eric E.
X.ds [T Practical Use of a Polymorphic Applicative Language
X.ds [B Proceedings of the 10th Symposium on Principles of Programming Languages
X.ds [I ACM
X.ds [P 237-255
X.nr [P 1
X.ds [D January 1983
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 3 article-in-book
X.ds [F 5
X.ds [F 11
X.]-
X.ds [K TICH07
X.ds [T A Data Model for Programming Support Environments and its Application
X.ds [A Tichy, Walter F.
X.ds [B Automated Tools for Information System Design and Development
X.ds [E Hans-Jochen Schneider and Anthony I. Wasserman
X.ds [C Amsterdam
X.ds [I North-Holland Publishing Company
X.ds [D 1982
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 3 article-in-book
X.ds [F 4
X.ds [F 2
X.ds [F 12
X.]-
X.ds [K HECK01
X.ds [T A Technique for Isolating Differences Between Files
X.ds [A Heckel, Paul
X.ds [J Communications of the ACM
X.ds [D April 1978
X.ds [V 21
X.ds [N 4
X.ds [P 264-268
X.nr [P 1
X.nr [T 0
X.nr [A 0
X.nr [O 0
X.][ 1 journal-article
X.ds [F 13
X.]-
X.ds [K TICH11
X.ds [T The String-to-String Correction Problem with Block Moves
X.ds [A Tichy, Walter F.
X.ds [D Nov. 1984
X.ds [J ACM Transactions on Computer Systems
X.ds [V 2
X.ds [N 4
X.ds [P 309-321
X.nr [P 1
X.nr [T 0
X.nr [A 1
X.nr [O 0
X.][ 1 journal-article
X.]>
SHAR_EOF
echo "extracting doc/rcs_functs.ms"
sed 's/^X//' << \SHAR_EOF > doc/rcs_functs.ms
X.SH
XFunctions of RCS (Revision Control System)
X.PP
XRCS manages software libraries. It greatly increases programmer productivity
Xby providing the following functions.
X.IP 1.
XRCS stores and retrieves multiple revisions of program and other text.
XThus, one can maintain one or more releases while developing the next
Xrelease, with a minimum of space overhead. Changes no longer destroy the
Xoriginal -- previous revisions remain accessible.
X.RS
X.IP a.
XMaintains each module as a tree of revisions.
X.IP b.
XProject libraries can
Xbe organized centrally, decentralized, or any way you like.
X.IP c.
XRCS works for any type of text: programs, documentation, memos, papers,
Xgraphics, VLSI layouts, form letters, etc.
X.RE
X.IP 2.
XRCS maintains a complete history of changes.
XThus, one can find out what happened to a module easily
Xand quickly, without having to compare source listings or
Xhaving to track down colleagues.
X.RS
X.IP a.
XRCS performs automatic record keeping.
X.IP b.
XRCS logs all changes automatically.
X.IP c.
XRCS guarantees project continuity.
X.RE
X.IP 3.
XRCS manages multiple lines of development.
X.IP 4.
XRCS can merge multiple lines of development.
XThus, when several parallel lines of development must be consolidated
Xinto one line, the merging of changes is automatic.
X.IP 5.
XRCS flags coding conflicts.
XIf two or more lines of development modify the same section of code,
XRCS can alert programmers about overlapping changes.
X.IP 6.
XRCS resolves access conflicts.
XWhen two or more programmers wish to modify the same revision,
XRCS alerts the programmers and makes sure that one modification won't wipe
Xout the other one.
X.IP 7.
XRCS provides high-level retrieval functions.
XRevisions can be retrieved according to ranges of revision numbers,
Xsymbolic names, dates, authors, and states.
X.IP 8.
XRCS provides release and configuration control.
XRevisions can be marked as released, stable, experimental, etc.
XConfigurations of modules can be described simply and directly.
X.IP 9.
XRCS performs automatic identification of modules with name, revision
Xnumber, creation time, author, etc.
XThus, it is always possible to determine which revisions of which
Xmodules make up a given configuration.
X.IP 10.
XProvides high-level management visibility.
XThus, it is easy to track the status of a software project.
X.RS
X.IP a.
XRCS provides a complete change history.
X.IP b.
XRCS records who did what when to which revision of which module.
X.RE
X.IP 11.
XRCS is fully compatible with existing software development tools.
XRCS is unobtrusive -- its interface to the file system is such that
Xall your existing software tools can be used as before.
X.IP 12.
XRCS' basic user interface is extremely simple. The novice need to learn
Xonly two commands. Its more sophisticated features have been
Xtuned towards advanced software development environments and the
Xexperienced software professional.
X.IP 13.
XRCS simplifies software distribution if customers
Xmaintain sources with RCS also. This technique assures proper
Xidentification of versions and configurations, and tracking of customer
Xmodifications. Customer modifications can be merged into distributed
Xversions locally or by the development group.
X.IP 14.
XRCS needs little extra space for the revisions (only the differences).
XIf intermediate revisions are deleted, the corresponding
Xdifferences are compressed into the shortest possible form.
X.IP 15.
XRCS is implemented with reverse deltas. This means that
Xthe latest revision, which is the one that is accessed most often,
Xis stored intact. All others are regenerated from the latest one
Xby applying reverse deltas (backward differences). This
Xresults in fast access time for the revision needed most often.
SHAR_EOF
echo "extracting doc/ci.1l"
sed 's/^X//' << \SHAR_EOF > doc/ci.1l
X.TH CI 1L "" "Purdue University"
X.SH NAME
Xci \- check in RCS revisions
X.SH SYNOPSIS
X.B ci
X[ options ]
Xfile ...
X.SH DESCRIPTION
X.I Ci
Xstores new revisions into RCS files.
XEach file name ending in `,v' is taken to be an RCS file, all others
Xare assumed to be working files containing new revisions.
X\fICi\fR deposits the contents of each working file
Xinto the corresponding RCS file.
XIf only a working file is given, \fIci\fR tries to find the corresponding
XRCS file in the directory ./RCS and then in the current directory.
XFor more details, see the file naming section below.
X.PP
XFor \fIci\fR to work, the caller's login must be on the access list,
Xexcept if the access list is empty or the caller is the superuser or the
Xowner of the file.
XTo append a new revision to an existing branch, the tip revision on
Xthat branch must be locked by the caller. Otherwise, only a
Xnew branch can be created. This restriction is not enforced
Xfor the owner of the file, unless locking is set to \fIstrict\fR
X(see
X.IR rcs (1L)).
XA lock held by someone else may be broken with the \fIrcs\fR command.
X.PP
XNormally, \fIci\fR checks whether the revision to be deposited is different
Xfrom the preceding one. If it is not different, \fIci\fR
Xeither aborts the deposit (if
X.B \-q
Xis given) or asks whether to abort
X(if
X.B \-q
Xis omitted). A deposit can be forced with the
X.B \-f
Xoption.
X.PP
XFor each revision deposited,
X.I ci
Xprompts for a log message.
XThe log message should summarize the change and must be terminated with
Xa line containing a single `.' or a control-D.
XIf several files are checked in, \fIci\fR asks whether to reuse the
Xprevious log message.
XIf the standard input is not a terminal, \fIci\fR suppresses the prompt
Xand uses the same log message for all files.
XSee also \fB\-m\fR.
X.PP
XThe number of the deposited revision can be given by any of the options
X\fB\-r\fR, \fB\-f\fR, \fB\-k\fR, \fB\-l\fR, \fB\-u\fR, or \fB\-q\fR.
X.PP
XIf the RCS file does not exist, \fIci\fR creates it and
Xdeposits the contents of the working file as the initial revision
X(default number: 1.1).
XThe access list is initialized to empty.
XInstead of the log message, \fIci\fR requests descriptive text (see
X\fB\-t\fR below).
X.TP 10
X.BR \-r [\fIrev\fR]
Xassigns the revision number \fIrev\fR
Xto the checked-in revision, releases the corresponding lock, and
Xdeletes the working file. This is the default.
X\fIRev\fR may be symbolic, numeric, or mixed.
X
XIf \fIrev\fR is a revision number, it must be higher than the latest
Xone on the branch to which \fIrev\fR belongs, or must start a new branch.
X
XIf \fIrev\fR is a branch rather than a revision number,
Xthe new revision is appended to that branch. The level number is obtained
Xby incrementing the tip revision number of that branch.
XIf \fIrev\fR indicates a non-existing branch,
Xthat branch is created with the initial revision numbered
X.IR rev .1.
X
X.ne 8
XIf \fIrev\fR is omitted, \fIci\fR tries to derive the new revision number from
Xthe caller's last lock. If the caller has locked the tip revision of a branch,
Xthe new revision is appended to that branch. The new revision number is obtained
Xby incrementing the tip revision number.
XIf the caller locked a non-tip revision, a new branch is started at
Xthat revision by incrementing the highest branch number at that revision.
XThe default initial branch and level numbers are 1.
X
XIf \fIrev\fR is omitted and the caller has no lock, but he is the owner
Xof the file and locking
Xis not set to \fIstrict\fR, then the revision is appended to the
Xdefault branch (normally the trunk; see the
X.B \-b
Xoption of
X.IR rcs (1L)).
X
XException: On the trunk, revisions can be appended to the end, but
Xnot inserted.
X.TP 10
X.BR \-f [\fIrev\fR]
Xforces a deposit; the new revision is deposited even it is not different
Xfrom the preceding one.
X.TP 10
X.BR \-k [\fIrev\fR]
Xsearches the working file for keyword values to determine its revision number,
Xcreation date, state, and author (see \fIco\fR(1)), and assigns these
Xvalues to the deposited revision, rather than computing them locally.
XIt also generates a default login message noting the login of the caller
Xand the actual checkin date.
XThis option is useful for software distribution. A revision that is sent to
Xseveral sites should be checked in with the \fB\-k\fR option at these sites to
Xpreserve the original number, date, author, and state.
XThe extracted keyword values and the default log message may be overridden
Xwith the options \fB\-r\fR, \fB\-d\fR, \fB\-s\fR, \fB\-w\fR, and \fB\-m\fR.
X.TP 10
X.BR \-l [\fIrev\fR]
Xworks like \fB\-r\fR, except it performs an additional \fIco \fB\-l\fR for the
Xdeposited revision. Thus, the deposited revision is immediately
Xchecked out again and locked.
XThis is useful for saving a revision although one wants to continue
Xediting it after the checkin.
X.TP 10
X.BR \-u [\fIrev\fR]
Xworks like \fB\-l\fR, except that the deposited revision is not locked.
XThis is useful if one wants to process (e.g., compile) the revision
Ximmediately after checkin.
X.TP 10
X.BR \-q [\fIrev\fR]
Xquiet mode; diagnostic output is not printed.
XA revision that is not different from the preceding one is not deposited,
Xunless \fB\-f\fR is given.
X.TP 10
X.BI \-d "date"
Xuses \fIdate\fR for the checkin date and time.
X\fIDate\fR may be specified in free format as explained in \fIco\fR(1).
XUseful for lying about the checkin date, and for
X.B \-k
Xif no date is available.
X.TP 10
X.BI \-m "msg"
Xuses the string \fImsg\fR as the log message for all revisions checked in.
X.TP 10
X.BI \-n "name"
Xassigns the symbolic name \fIname\fR to the number of the checked-in revision.
X\fICi\fR prints an error message if \fIname\fR is already assigned to another
Xnumber.
X.TP 10
X.BI \-N "name"
Xsame as \fB\-n\fR, except that it overrides a previous assignment of \fIname\fR.
X.TP
X.BI \-s "state"
Xsets the state of the checked-in revision to the identifier \fIstate\fR.
XThe default is \fIExp\fR.
X.TP
X.BR \-t [\fItxtfile\fR]
Xwrites descriptive text into the RCS file (deletes the existing text).
XIf \fItxtfile\fR is omitted,
X\fIci\fR prompts the user for text supplied from the standard input,
Xterminated with a line containing a single `.' or control-D.
XOtherwise, the descriptive text is copied from the file \fItxtfile\fR.
XDuring initialization, descriptive text is requested
Xeven if \fB\-t\fR is not given.
XThe prompt is suppressed if standard input is not a terminal.
X.TP
X.BI \-w "login"
Xuses \fIlogin\fR for the author field of the deposited revision.
XUseful for lying about the author, and for
X.B \-k
Xif no author is available.
X.SH "FILE NAMING"
XPairs of RCS files and working files may be specified in 3 ways (see also the
Xexample section of \fIco\fR(1)).
X.PP
X1) Both the RCS file and the working file are given. The RCS file name is of
Xthe form \fIpath1/workfile,v\fR
Xand the working file name is of the form
X\fIpath2/workfile\fR, where
X\fIpath1/\fR and
X\fIpath2/\fR are (possibly different or empty) paths and
X\fIworkfile\fR is a file name.
X.PP
X2) Only the RCS file is given.
XThen the working file is assumed to be in the current
Xdirectory and its name is derived from the name of the RCS file
Xby removing \fIpath1/\fR and the suffix \fI,v\fR.
X.PP
X3) Only the working file is given.
XThen \fIci\fR looks for an RCS file of the form
X\fIpath2/RCS/workfile,v\fR or \fIpath2/workfile,v\fR (in this order).
X.PP
XIf the RCS file is specified without a path in 1) and 2), then \fIci\fR
Xlooks for the RCS file first in the directory ./RCS and then in the current
Xdirectory.
X.SH "FILE MODES"
XAn RCS file created by \fIci\fR inherits the read and execute permissions
Xfrom the working file. If the RCS file exists already, \fIci\fR
Xpreserves its read and execute permissions.
X\fICi\fR always turns off all write permissions of RCS files.
X.SH FILES
XThe caller of the command
Xmust have read/write permission for the directories containing
Xthe RCS file and the working file, and read permission for the RCS file itself.
XA number of temporary files are created.
XA semaphore file is created in the directory containing the RCS file.
X\fICi\fR always creates a new RCS file and unlinks the old one.
XThis strategy makes links to RCS files useless.
X.SH DIAGNOSTICS
XFor each revision,
X\fIci\fR prints the RCS file, the working file, and the number
Xof both the deposited and the preceding revision.
XThe exit status always refers to the last file checked in,
Xand is 0 if the operation was successful, 1 otherwise.
X.SH IDENTIFICATION
X.de VL
X\\$2
X..
XAuthor: Walter F. Tichy,
XPurdue University, West Lafayette, IN, 47907.
X.sp 0
XRevision Number:
X.VL $Revision: 1.3 $
X; Release Date:
X.VL $Date: 89/05/02 11:12:08 $
X\&.
X.sp 0
XCopyright \(co 1982, 1988, 1989 by Walter F. Tichy.
X.SH SEE ALSO
Xco(1L), ident(1L), rcs(1L), rcsdiff(1L), rcsintro(1L), rcsmerge(1L), rlog(1L),
Xrcsfile(5L)
X.sp 0
XWalter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control
XSystem," in \fIProceedings of the 6th International Conference on Software
XEngineering\fR, IEEE, Tokyo, Sept. 1982.
SHAR_EOF
echo "extracting doc/co.1l"
sed 's/^X//' << \SHAR_EOF > doc/co.1l
X.TH CO 1L "" "Purdue University"
X.SH NAME
Xco \- check out RCS revisions
X.SH SYNOPSIS
X.B co
X[ options ]
Xfile ...
X.SH DESCRIPTION
X.I Co
Xretrieves a revision from each RCS file and stores it into
Xthe corresponding working file.
XEach file name ending in `,v' is taken to be an RCS file;
Xall other files are assumed to be working files.
XIf only a working file is given, \fIco\fR tries to find the corresponding
XRCS file in the directory ./RCS and then in the current directory.
XFor more details, see the file naming section below.
X.PP
XRevisions of an RCS file may be checked out locked or unlocked. Locking a
Xrevision prevents overlapping updates. A revision checked out for reading or
Xprocessing (e.g., compiling) need not be locked. A revision checked out
Xfor editing and later checkin must normally be locked. \fICo\fR with locking
Xfails if the revision to be checked out is currently locked by another user.
X(A lock may be broken with the
X.IR rcs (1L)
Xcommand.)
X\fICo\fR with locking also requires the caller to be on the access list of
Xthe RCS file, unless he is the owner of the
Xfile or the superuser, or the access list is empty.
X\fICo\fR without locking is not subject to accesslist restrictions, and is
Xnot affected by the presence of locks.
X.PP
XA revision is selected by options for revision or branch number,
Xcheckin date/time, author, or state.
XWhen the selection options
Xare applied in combination, \fIco\fR retrieves the latest revision
Xthat satisfies all of them.
XIf none of the selection options
Xis specified, \fIco\fR retrieves the latest revision
Xon the default branch (normally the trunk, see the
X.B \-b
Xoption of
X.IR rcs (1L)).
XA revision or branch number may be attached
Xto any of the options
X\fB\-f\fR, \fB\-l\fR, \fB\-p\fR, \fB\-q\fR, \fB\-r\fR, or \fB\-u\fR.
XThe options \fB\-d\fR (date), \fB\-s\fR (state), and \fB\-w\fR (author)
Xretrieve from a single branch, the \fIselected\fR branch,
Xwhich is either specified by one of
X\fB\-f\fR,..., \fB\-u\fR, or the default branch.
X.PP
XA \fIco\fR command applied to an RCS
Xfile with no revisions creates a zero-length working file.
X\fICo\fR always performs keyword substitution (see below).
X.PP
X.TP 11
X.BR \-r [\fIrev\fR]
Xretrieves the latest revision whose number is less than or equal to \fIrev\fR.
XIf \fIrev\fR indicates a branch rather than a revision,
Xthe latest revision on that branch is retrieved.
XIf \fIrev\fR is omitted, the latest revision on the default branch
X(see the
X.B \-b
Xoption of
X.IR rcs (1L))
Xis retrieved.
X\fIRev\fR is composed of one or more numeric or symbolic fields
Xseparated by `.'. The numeric equivalent of a symbolic field
Xis specified with the \fB\-n\fR option of the commands
X.IR ci (1L)
Xand
X.IR rcs (1L).
X.TP 11
X.BR \-l [\fIrev\fR]
Xsame as \fB\-r\fR, except that it also locks the retrieved revision for
Xthe caller. See option \fB\-r\fR for handling of the revision number
X.I rev .
X.TP 11
X.BR \-u [\fIrev\fR]
Xsame as \fB\-r\fR, except that it unlocks the retrieved revision (if it was
Xlocked by the caller). If \fIrev\fR is omitted, \fB\-u\fR
Xretrieves the latest revision locked by the caller; if no such lock exists,
Xit retrieves the latest revision on the default branch.
X.TP 11
X.BR \-f [\fIrev\fR]
Xforces the overwriting of the working file;
Xuseful in connection with \fB\-q\fR.
XSee also the section on file modes below.
X.TP 11
X.BR \-p [\fIrev\fR]
Xprints the retrieved revision on the standard output rather than storing it
Xin the working file.
XThis option is useful when \fIco\fR
Xis part of a pipe.
X.TP 11
X.BR \-q [\fIrev\fR]
Xquiet mode; diagnostics are not printed.
X.TP 11
X.BI \-d "date"
Xretrieves the latest revision on the selected branch whose checkin date/time is less than or equal to \fIdate\fR.
XThe date and time may be given in free format and are converted to local time.
XExamples of formats for \fIdate\fR:
X.ne 5
X.nf
X
X\fI22-April-1982, 17:20-CDT,
X2:25 AM, Dec. 29, 1983,
XTue-PDT, 1981, 4pm Jul 21\fR \fR(free format),
X\fIFri, April 16 15:52:25 EST 1982 \fR(output of ctime).
X.fi
X
XMost fields in the date and time may be defaulted.
X\fICo\fR determines the defaults in the order year, month, day,
Xhour, minute, and second (most to least significant). At least one of these
Xfields must be provided. For omitted fields that are of higher significance
Xthan the highest provided field,
Xthe current values are assumed. For all other omitted fields,
Xthe lowest possible values are assumed.
XFor example, the date "20, 10:30" defaults to
X10:30:00 of the 20th of the current month and current year.
XThe date/time must be quoted if it contains spaces.
X.TP 11
X.BI \-s "state"
Xretrieves the latest revision on the selected branch whose state is set to \fIstate\fR.
X.TP 11
X.BR \-w [\fIlogin\fR]
Xretrieves the latest revision on the selected branch which was checked in
Xby the user with login name \fIlogin\fR. If the argument \fIlogin\fR is
Xomitted, the caller's login is assumed.
X.TP 11
X.BI \-j joinlist
Xgenerates a new revision which is the join of the revisions on \fIjoinlist\fR.
X\fIJoinlist\fR is a comma-separated list of pairs of the form
X\fIrev2:rev3\fR, where \fIrev2\fR and \fIrev3\fR are (symbolic or numeric)
Xrevision numbers.
XFor the initial such pair, \fIrev1\fR denotes the revision selected
Xby the above options \fB\-r\fR, ..., \fB\-w\fR. For all other pairs, \fIrev1\fR
Xdenotes the revision generated by the previous pair. (Thus, the output
Xof one join becomes the input to the next.)
X
XFor each pair, \fIco\fR joins revisions \fIrev1\fR and \fIrev3\fR
Xwith respect to \fIrev2\fR.
XThis means that all changes that transform
X\fIrev2\fR into \fIrev1\fR are applied to a copy of \fIrev3\fR.
XThis is particularly useful if \fIrev1\fR
Xand \fIrev3\fR are the ends of two branches that have \fIrev2\fR as a common
Xancestor. If \fIrev1\fR < \fIrev2\fR < \fIrev3\fR on the same branch,
Xjoining generates a new revision which is like \fIrev3\fR, but with all
Xchanges that lead from \fIrev1\fR to \fIrev2\fR undone.
XIf changes from \fIrev2\fR to \fIrev1\fR overlap with changes from
X\fIrev2\fR to \fIrev3\fR, \fIco\fR prints a warning and includes the
Xoverlapping sections, delimited by the lines \fI<<<<<<<\ rev1,
X=======\fR, and \fI>>>>>>>\ rev3\fR.
X
XFor the initial pair, \fIrev2\fR may be omitted. The default is the common
Xancestor.
XIf any of the arguments indicate branches, the latest revisions
Xon those branches are assumed.
XThe options \fB\-l\fR and \fB\-u\fR lock or unlock \fIrev1\fR.
X.SH "KEYWORD SUBSTITUTION"
XStrings of the form \fI$keyword$\fR and \fI$keyword:...$\fR embedded in
Xthe text are replaced
Xwith strings of the form \fI$keyword:\ value\ $\fR,
Xwhere \fIkeyword\fR and \fIvalue\fR are pairs listed below.
XKeywords may be embedded in literal strings
Xor comments to identify a revision.
X.PP
XInitially, the user enters strings of the form \fI$keyword$\fR.
XOn checkout, \fIco\fR replaces these strings with strings of the form
X\fI$keyword:\ value\ $\fR. If a revision containing strings of the latter form
Xis checked back in, the value fields will be replaced during the next
Xcheckout.
XThus, the keyword values are automatically updated on checkout.
X.PP
XKeywords and their corresponding values:
X.TP 13
X$\&Author$
XThe login name of the user who checked in the revision.
X.TP
X$\&Date$
XThe date and time the revision was checked in.
X.TP
X$\&Header$
XA standard header containing the full pathname of the RCS file, the
Xrevision number, the date, the author, the state, and the locker (if locked).
X.TP
X$\&Id$
XSame as $\&Header$, except that the RCS file name is without a path.
X.TP
X$\&Locker$
XThe login name of the user who locked the revision (empty if not locked).
X.TP
X$\&Log$
XThe log message supplied during checkin, preceded by a header
Xcontaining the RCS file name, the revision number, the author, and the date.
XExisting log messages are NOT replaced.
XInstead, the new log message is inserted after \fI$\&Log:...$\fR.
XThis is useful for
Xaccumulating a complete change log in a source file.
X.TP
X$\&RCSfile$
XThe name of the RCS file without path.
X.TP
X$\&Revision$
XThe revision number assigned to the revision.
X.TP
X$\&Source$
XThe full pathname of the RCS file.
X.TP
X$\&State$
XThe state assigned to the revision with the
X.B \-s
Xoption of
X.IR rcs (1L)
Xor
X.IR ci (1L).
X.TP
X.SH "FILE NAMING"
XPairs of RCS files and working files may be specified in 3 ways (see also the
Xexample section).
X.PP
X1) Both the RCS file and the working file are given. The RCS file name is of
Xthe form \fIpath1/workfile,v\fR
Xand the working file name is of the form
X\fIpath2/workfile\fR, where
X\fIpath1/\fR and
X\fIpath2/\fR are (possibly different or empty) paths and
X\fIworkfile\fR is a file name.
X.PP
X2) Only the RCS file is given. Then the working file is created in the current
Xdirectory and its name is derived from the name of the RCS file
Xby removing \fIpath1/\fR and the suffix \fI,v\fR.
X.PP
X3) Only the working file is given.
XThen \fIco\fR looks for an RCS file of the form
X\fIpath2/RCS/workfile,v\fR or \fIpath2/workfile,v\fR (in this order).
X.PP
XIf the RCS file is specified without a path in 1) and 2), then \fIco\fR
Xlooks for the RCS file first in the directory ./RCS and then in the current
Xdirectory.
X.SH EXAMPLES
XSuppose the current directory contains a subdirectory `RCS' with an RCS file
X`io.c,v'. Then all of the following commands retrieve the latest
Xrevision from `RCS/io.c,v' and store it into `io.c'.
X.nf
X.sp
X co io.c; co RCS/io.c,v; co io.c,v;
X co io.c RCS/io.c,v; co io.c io.c,v;
X co RCS/io.c,v io.c; co io.c,v io.c;
X.fi
X.SH "FILE MODES"
XThe working file inherits the read and execute permissions from the RCS
Xfile. In addition, the owner write permission is turned on, unless the file
Xis checked out unlocked and locking is set to \fIstrict\fR (see
X.IR rcs (1L)).
X.PP
XIf a file with the name of the working file exists already and has write
Xpermission, \fIco\fR aborts the checkout if \fB\-q\fR is given, or asks
Xwhether to abort if \fB\-q\fR is not given. If the existing working file is
Xnot writable or \fB\-f\fR is given, the working file is deleted without asking.
X.SH FILES
XThe caller of the command must have write permission in the working
Xdirectory, read permission for the RCS file, and either read permission
X(for reading) or read/write permission (for locking) in the directory which
Xcontains the RCS file.
X.PP
XA number of temporary files are created.
XA semaphore file is created in the directory of the RCS file
Xto prevent simultaneous update.
X.SH DIAGNOSTICS
XThe RCS file name, the working file name,
Xand the revision number retrieved are
Xwritten to the diagnostic output.
XThe exit status always refers to the last file checked out,
Xand is 0 if the operation was successful, 1 otherwise.
X.SH IDENTIFICATION
X.de VL
X\\$2
X..
XAuthor: Walter F. Tichy,
XPurdue University, West Lafayette, IN, 47907.
X.sp 0
XRevision Number:
X.VL $Revision: 1.4 $
X; Release Date:
X.VL $Date: 89/05/02 11:20:22 $
X\&.
X.sp 0
XCopyright \(co 1982, 1988, 1989 by Walter F. Tichy.
X.SH SEE ALSO
Xci(1L), ident(1L), rcs(1L), rcsdiff(1L), rcsintro(1L), rcsmerge(1L), rlog(1L),
Xrcsfile(5L)
X.sp 0
XWalter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control
XSystem," in \fIProceedings of the 6th International Conference on Software
XEngineering\fR, IEEE, Tokyo, Sept. 1982.
X.SH LIMITATIONS
XThe option \fB\-d\fR gets confused in some circumstances,
Xand accepts no date before 1970.
XLinks to the RCS and working files are not preserved.
XThere is no way to suppress the expansion of keywords, except
Xby writing them differently. In nroff and troff, this is done by embedding the
Xnull-character `\\&' into the keyword.
X.SH BUGS
XThe option \fB\-j\fR does not work for
Xfiles that contain lines with a single `.'.
SHAR_EOF
echo "extracting doc/ident.1l"
sed 's/^X//' << \SHAR_EOF > doc/ident.1l
X.TH IDENT 1L "" "Purdue University"
X.SH NAME
Xident \- identify files
X.SH SYNOPSIS
X\fBident\fR [ \fB\-q\fR ] [ file ... ]
X.SH DESCRIPTION
X.I Ident
Xsearches the named files or, if no file name appears, the standard input
Xfor all occurrences of the pattern
X\fI$keyword:...$\fR, where \fIkeyword\fR is one of
X.nf
X
X Author
X Date
X Header
X Id
X Locker
X Log
X Revision
X RCSfile
X Source
X State
X
X.fi
XThese patterns are normally inserted automatically by the RCS command
X.IR co (1L),
Xbut can also be inserted manually. The option \fB\-q\fR suppresses
Xthe warning given if there are no patterns in a file.
X.PP
X\fIIdent\fR works on text files as well as object files and dumps.
XFor example, if the C program in file f.c contains
X.nf
X
X char rcsid[] = "$\&Header: Header information $";
X
X.fi
Xand f.c is compiled into f.o, then the command
X.nf
X
X ident f.c f.o
X
Xwill print
X
X f.c:
X $\&Header: Header information $
X f.o:
X $\&Header: Header information $
X
X.SH IDENTIFICATION
X.de VL
X\\$2
X..
XAuthor: Walter F. Tichy,
XPurdue University, West Lafayette, IN, 47907.
X.sp 0
XRevision Number:
X.VL $Revision: 1.2 $
X; Release Date:
X.VL $Date: 89/05/02 11:13:09 $
X\&.
X.sp 0
XCopyright \(co 1982, 1988, 1989 by Walter F. Tichy.
X.SH SEE ALSO
Xci(1L), co(1L), rcs(1L), rcsdiff(1L), rcsintro(1L), rcsmerge(1L), rlog(1L), rcsfile(5L),
X.sp 0
XWalter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control
XSystem," in \fIProceedings of the 6th International Conference on Software
XEngineering\fR, IEEE, Tokyo, Sept. 1982.
SHAR_EOF
echo "extracting doc/merge.1l"
sed 's/^X//' << \SHAR_EOF > doc/merge.1l
X.TH MERGE 1L "" "Purdue University"
X.SH NAME
Xmerge \- three-way file merge
X.SH SYNOPSIS
X\fBmerge\fR [ \fB-p\fR ] file1 file2 file3
X.SH DESCRIPTION
X.I Merge
Xincorporates all changes that lead form \fIfile2\fR to \fIfile3\fR into
X\fIfile1\fR. The result goes to std. output if \fB-p\fR is present, into
X\fIfile1\fR otherwise. \fIMerge\fR is useful for combining separate changes
Xto an original. Suppose \fIfile2\fR is the original, and both \fIfile1\fR
Xand \fIfile3\fR are modifications of \fIfile2\fR. Then \fImerge\fR
Xcombines both changes.
X.PP
XAn overlap occurs if both \fIfile1\fR and \fIfile3\fR
Xhave changes in a common segment of lines.
X\fIMerge\fR prints how many overlaps occurred, and includes both alternatives
Xin the result. The alternatives are delimited as follows:
X.sp
X.nf
X <<<<<<< file1
X lines in file1
X =======
X lines in file3
X >>>>>>> file3
X.fi
X.sp
XIf there are overlaps, the user should edit the result and delete one of the
Xalternatives.
X.SH IDENTIFICATION
X.de VL
X\\$2
X..
XAuthor: Walter F. Tichy,
XPurdue University, West Lafayette, IN, 47907.
X.sp 0
XRevision Number:
X.VL $Revision: 1.2 $
X; Release Date:
X.VL $Date: 89/05/02 11:13:46 $
X\&.
X.sp 0
XCopyright \(co 1982, 1988, 1989 by Walter F. Tichy.
X.SH SEE ALSO
Xdiff3 (1), diff (1), rcsmerge (1L), co (1L).
SHAR_EOF
echo "End of archive 5 (of 14)"
# if you want to concatenate archives, remove anything after this line
exit