1 .\" Format this file with:
2 .\" pic file | tbl | troff -ms
4 .\" \*s stands for $, and avoids problems when this file is checked in.
21 .Id $FreeBSD: src/gnu/usr.bin/rcs/doc/rcs.ms,v 1.5 1999/08/27 23:36:41 peter Exp $
22 .Id $DragonFly: src/gnu/usr.bin/rcs/doc/rcs.ms,v 1.2 2003/06/17 04:25:47 dillon Exp $
25 RCS\*-A System for Version Control
30 Department of Computer Sciences
32 West Lafayette, Indiana 47907
35 An important problem in program development and maintenance is version control,
36 i.e., the task of keeping a software system consisting of many versions and
37 configurations well organized.
38 The Revision Control System (RCS)
39 is a software tool that assists with that task.
40 RCS manages revisions of text documents, in particular source programs,
41 documentation, and test data.
42 It automates the storing, retrieval, logging and identification of revisions,
43 and it provides selection mechanisms for composing configurations.
44 This paper introduces basic version control concepts and
45 discusses the practice of version control
47 For conserving space, RCS stores deltas, i.e., differences between
48 successive revisions. Several delta storage methods are discussed.
49 Usage statistics show that RCS's delta storage method is
50 space and time efficient.
51 The paper concludes with a detailed survey of version control tools.
53 \fBKeywords\fR: configuration management, history management,
54 version control, revisions, deltas.
57 An earlier version of this paper was published in
58 .I "Software\*-Practice & Experience"
60 7 (July 1985), 637-654.
67 Version control is the task of keeping software
68 systems consisting of many versions and configurations well organized.
69 The Revision Control System (RCS) is a set of UNIX
70 commands that assist with that task.
72 RCS' primary function is to manage \fIrevision groups\fR.
73 A revision group is a set of text documents, called \fIrevisions\fR,
74 that evolved from each other. A new revision is
75 created by manually editing an existing one.
76 RCS organizes the revisions into an ancestral tree. The initial revision
77 is the root of the tree, and the tree edges indicate
78 from which revision a given one evolved.
79 Besides managing individual revision groups, RCS provides
80 flexible selection functions for composing configurations.
81 RCS may be combined with MAKE\u1\d,
82 resulting in a powerful package for version control.
84 RCS also offers facilities for
85 merging updates with customer modifications,
86 for distributed software development, and
87 for automatic identification.
88 Identification is the `stamping'
89 of revisions and configurations with unique markers.
90 These markers are akin to serial numbers,
91 telling software maintainers unambiguously which configuration
94 RCS is designed for both production and experimental
96 In production environments,
97 access controls detect update conflicts and prevent overlapping changes.
98 In experimental environments, where strong controls are
99 counterproductive, it is possible to loosen the controls.
101 Although RCS was originally intended for programs, it is useful for any
102 text that is revised frequently and whose previous revisions must be
103 preserved. RCS has been applied successfully to store the source
104 text for drawings, VLSI layouts, documentation, specifications,
105 test data, form letters and articles.
107 This paper discusses the practice of
108 version control using RCS.
109 It also introduces basic version control concepts,
110 useful for clarifying current practice and designing similar systems.
111 Revision groups of individual components are treated in the next three sections,
112 and the extensions to configurations follow.
113 Because of its size, a survey of version control tools
114 appears at the end of the paper.
116 Getting started with RCS
118 Suppose a text file \fIf.c\fR is to be placed under control of RCS.
119 Invoking the check-in command
123 creates a new revision group with the contents of
124 \fIf.c\fR as the initial
125 revision (numbered 1.1)
126 and stores the group into the file \fIf.c,v\fR.
127 Unless told otherwise, the command deletes \fIf.c\fR.
128 It also asks for a description of the group.
129 The description should state the common purpose of all revisions in the group,
130 and becomes part of the group's documentation.
131 All later check-in commands will ask for a log entry,
132 which should summarize the changes made.
133 (The first revision is assigned a default log message,
134 which just records the fact that it is the initial revision.)
136 Files ending in \fI,v\fR
137 are called \fIRCS files\fR (\fIv\fR stands for \fIv\fRersions);
138 the others are called working files.
139 To get back the working file \fIf.c\fR in the previous example,
140 execute the check-out command:
145 This command extracts the latest revision from
146 the revision group \fIf.c,v\fR and writes
148 The file \fIf.c\fR can now be edited and, when finished,
149 checked back in with \fIci\fR:
153 \fICi\fR assigns number 1.2 to
155 If \fIci\fR complains with the message
157 ci error: no lock set by <login>
159 then the system administrator has decided to configure RCS for a
160 production environment by enabling the `strict locking feature'.
161 If this feature is enabled, all RCS files are initialized
162 such that check-in operations require a lock on the previous revision
163 (the one from which the current one evolved).
164 Locking prevents overlapping modifications if several people work on the same file.
165 If locking is required, the revision should
166 have been locked during the check-out by using
167 the option \fI\-l\fR:
171 Of course it is too late now for the check-out with locking, because
172 \fIf.c\fR has already been changed; checking out the file again
173 would overwrite the modifications.
174 (To prevent accidental overwrites, \fIco\fR senses the presence
175 of a working file and asks whether the user really intended to overwrite it.
176 The overwriting check-out is sometimes useful for
177 backing up to the previous revision.)
178 To be able to proceed with the check-in in the present case, first execute
182 This command retroactively locks the latest revision, unless someone
183 else locked it in the meantime. In this case, the two programmers
184 involved have to negotiate whose
185 modifications should take precedence.
187 If an RCS file is private, i.e., if only the owner of the file is expected
188 to deposit revisions into it, the strict locking feature is unnecessary and
190 If strict locking is disabled,
191 the owner of the RCS file need not have a lock for check-in.
192 For safety reasons, all others
193 still do. Turning strict locking off and on is done with the commands:
195 rcs \-U f.c \fRand\fP rcs \-L f.c
197 These commands enable or disable the strict locking feature for each RCS file
199 The system administrator only decides whether strict locking is
202 To reduce the clutter in a working directory, all RCS files can be moved
203 to a subdirectory with the name \fIRCS\fR.
204 RCS commands look first into that directory for RCS files.
205 All the commands presented above work
206 with the \fIRCS\fR subdirectory without change.\(dg
208 Pairs of RCS and working files can actually be specified in 3 ways:
209 a) both are given, b) only the working file is given, c) only the
211 If a pair is given, both files may have arbitrary path prefixes;
212 RCS commands pair them up intelligently.
215 It may be undesirable that \fIci\fR deletes the working file.
216 For instance, sometimes one would like to save the current revision,
217 but continue editing.
222 checks in \fIf.c\fR as usual, but performs an additional
223 check-out with locking afterwards. Thus, the working file does
224 not disappear after the check-in.
225 Similarly, the option
226 \fI\-u\fR does a check-in followed by a check-out without
227 locking. This option is useful if the file is needed for compilation after the check-in.
228 Both options update the identification markers in the working file
231 Besides the operations \fIci\fR and \fIco\fR, RCS provides the following
239 ident%extract identification markers
240 rcs%change RCS file attributes
241 rcsclean%remove unchanged working files (optional)
242 rcsdiff%compare revisions
243 rcsfreeze%record a configuration (optional)
244 rcsmerge%merge revisions
245 rlog%read log messages and other information in RCS files
247 A synopsis of these commands appears in the Appendix.
249 Automatic Identification
251 RCS can stamp source and object code with special identification strings,
252 similar to product and serial numbers.
253 To obtain such identification, place the marker
257 into the text of a revision, for instance inside a comment.
258 The check-out operation will replace this marker with a string of the form
260 \*sId: filename revisionnumber date time author state locker \*s
262 This string need never be touched, because \fIco\fR keeps it
263 up to date automatically.
264 To propagate the marker into object code, simply put
265 it into a literal character string. In C, this is done as follows:
267 static char rcsid[] = \&"\*sId\*s\&";
269 The command \fIident\fR extracts such markers from any file, in particular from
271 \fIIdent\fR helps to find out
272 which revisions of which modules were used in a given program.
273 It returns a complete and unambiguous component list,
274 from which a copy of the program can be reconstructed.
275 This facility is invaluable for program maintenance.
277 There are several additional identification markers, one for each component
283 has a similar function. It accumulates
284 the log messages that are requested during check-in.
285 Thus, one can maintain the complete history of a revision directly inside it,
286 by enclosing it in a comment.
287 Figure 1 is an edited version of a log contained in revision 4.1 of
288 the file \fIci.c\fR. The log appears at the beginning of the file,
289 and makes it easy to determine what the recent modifications were.
299 * Revision 4.1 1983/05/10 17:03:06 wft
300 * Added option \-d and \-w, and updated assignment of date, etc. to new delta.
301 * Added handling of default branches.
303 * Revision 3.9 1983/02/15 15:25:44 wft
304 * Added call to fastcopy() to copy remainder of RCS file.
306 * Revision 3.8 1983/01/14 15:34:05 wft
307 * Added ignoring of interrupts while new RCS file is renamed;
308 * avoids deletion of RCS files by interrupts.
310 * Revision 3.7 1982/12/10 16:09:20 wft
311 * Corrected checking of return code from diff.
312 * An RCS file now inherits its mode during the first ci from the working file,
313 * except that write permission is removed.
317 Figure 1. Log entries produced by the marker \*sLog\*s.
323 Since revisions are stored in the form of differences,
325 physically stored once,
326 independent of the number of revisions present.
327 Thus, the \*sLog\*s marker incurs negligible space overhead.
329 The RCS Revision Tree
331 RCS arranges revisions in an ancestral tree.
332 The \fIci\fR command builds this tree; the auxiliary command \fIrcs\fR
334 The tree has a root revision, normally numbered 1.1, and successive revisions
335 are numbered 1.2, 1.3, etc. The first field of a revision number
336 is called the \fIrelease number\fR and the second one
337 the \fIlevel number\fR. Unless given explicitly,
338 the \fIci\fR command assigns a new revision number
339 by incrementing the level number of the previous revision.
340 The release number must be incremented explicitly, using the
341 \fI\-r\fR option of \fIci\fR.
342 Assuming there are revisions 1.1, 1.2, and 1.3 in the RCS file f.c,v, the command
344 ci \-r2.1 f.c \fRor\fP ci \-r2 f.c
346 assigns the number 2.1 to the new revision.
347 Later check-ins without the \fI\-r\fR option will assign the numbers 2.2, 2.3,
349 The release number should be incremented only at major transition points
350 in the development, for instance when a new release of a software product has
353 When are branches needed?
355 A young revision tree is slender:
356 It consists of only one branch, called the trunk.
357 As the tree ages, side branches may form.
358 Branches are needed in the following 4 situations.
359 .IP "\fITemporary fixes\fR"
361 Suppose a tree has 5 revisions grouped in 2 releases,
362 as illustrated in Figure 2.
363 Revision 1.3, the last one of release 1, is in operation at customer sites,
364 while release 2 is in active development.
381 Figure 2. A slender revision tree.
383 Now imagine a customer requesting a fix of
384 a problem in revision 1.3, although actual development has moved on
385 to release 2. RCS does not permit an extra
386 revision to be spliced in between 1.3 and 2.1, since that would not reflect
387 the actual development history. Instead, create a branch
388 at revision 1.3, and check in the fix on that branch.
389 The first branch starting at 1.3 has number 1.3.1, and
390 the revisions on that branch are numbered 1.3.1.1, 1.3.1.2, etc.
391 The double numbering is needed to allow for another
392 branch at 1.3, say 1.3.2.
393 Revisions on the second branch would be numbered
394 1.3.2.1, 1.3.2.2, and so on.
395 The following steps create
396 branch 1.3.1 and add revision 1.3.1.1:
404 %co \-r1.3 f.c% \*- check out revision 1.3
405 %edit f.c% \*- change it
406 %ci \-r1.3.1 f.c% \*- check it in on branch 1.3.1
411 This sequence of commands transforms the tree of Figure 2 into
413 Note that it may be necessary to incorporate the differences
414 between 1.3 and 1.3.1.1
415 into a revision at level 2. The operation \fIrcsmerge\fR automates this
416 process (see the Appendix).
430 line invis down from R21.s
432 arrow dashed right from RB1.e
433 arrow from R13.s to RB1.w
437 Figure 3. A revision tree with one side branch
439 .IP "\fIDistributed development and customer modifications\fR"
441 Assume a situation as in Figure 2, where revision 1.3 is in operation
442 at several customer sites,
443 while release 2 is in development.
444 Customer sites should use RCS to store the distributed software.
445 However, customer modifications should not be placed on the same branch
446 as the distributed source; instead, they should be placed on a side branch.
447 When the next software distribution arrives,
448 it should be appended to the trunk of
449 the customer's RCS file, and the customer
450 can then merge the local modifications back into the new release.
451 In the above example, a
452 customer's RCS file would contain the following tree, assuming
453 that the customer has received revision 1.3, added his local modifications
454 as revision 1.3.1.1, then received revision 2.4, and merged
455 2.4 and 1.3.1.1, resulting in 2.4.1.1.
469 arrow from R13.e to R24.w
470 line invis down from R21.s
472 arrow from R13.s to RB1.w
474 line invis down from R25.s
476 arrow from R24.s to RB2.w
480 Figure 4. A customer's revision tree with local modifications.
482 This approach is actually practiced in the CSNET project,
483 where several universities and a company cooperate
484 in developing a national computer network.
485 .IP "\fIParallel development\fR"
487 Sometimes it is desirable to explore an alternate design or
488 a different implementation technique in parallel with the
489 main line development. Such development
490 should be carried out on a side branch.
491 The experimental changes may later be moved into the main line, or abandoned.
492 .IP "\fIConflicting updates\fR"
494 A common occurrence is that one programmer
495 has checked out a revision, but cannot complete the assignment
496 for some reason. In the meantime, another person
497 must perform another modification
498 immediately. In that case, the second person should check-out the same revision,
499 modify it, and check it in on a side branch, for later merging.
501 Every node in a revision tree consists of the following attributes:
502 a revision number, a check-in date and time, the author's identification,
503 a log entry, a state and the actual text. All these attributes
504 are determined at the time the revision is checked in.
505 The state attribute indicates the status of a revision.
506 It is set automatically to `experimental' during check-in.
507 A revision can later be promoted to a higher status, for example
508 `stable' or `released'. The set of states is user-defined.
510 Revisions are represented as deltas
512 For conserving space, RCS stores revisions in the form
513 of deltas, i.e., as differences between revisions.
514 The user interface completely hides this fact.
516 A delta is a sequence of edit commands that transforms one string
517 into another. The deltas employed by RCS are line-based, which means
518 that the only edit commands allowed are insertion and deletion of lines.
519 If a single character in a line is changed, the
520 edit scripts consider the entire line changed.
521 The program \fIdiff\fR\u2\d
522 produces a small, line-based delta between pairs of text files.
523 A character-based edit script would take much longer to compute,
524 and would not be significantly shorter.
526 Using deltas is a classical space-time tradeoff: deltas reduce the
527 space consumed, but increase access time.
528 However, a version control tool should impose as little delay
529 as possible on programmers.
530 Excessive delays discourage the use of version controls,
531 or induce programmers to take shortcuts that compromise system integrity.
532 To gain reasonably fast access time for both editing and compiling,
533 RCS arranges deltas in the following way.
534 The most recent revision on the trunk is stored intact.
535 All other revisions on the trunk are stored as reverse deltas.
536 A reverse delta describes how to go backward in the development history:
537 it produces the desired revision if applied to the successor of that revision.
538 This implementation has the advantage
539 that extraction of the latest revision is a simple and fast copy
541 Adding a new revision to the trunk is also fast: \fIci\fR simply
542 adds the new revision intact, replaces the previous
543 revision with a reverse delta, and keeps the rest of the old deltas.
544 Thus, \fIci\fR requires the computation
545 of only one new delta.
547 Branches need special treatment. The naive solution would be to
548 store complete copies for the tips of all branches.
549 Clearly, this approach would cost too much space. Instead,
550 RCS uses \fIforward\fR deltas for branches. Regenerating a revision
551 on a side branch proceeds as follows. First, extract the latest revision
552 on the trunk; secondly, apply reverse deltas until the fork revision for
553 the branch is obtained; thirdly, apply forward deltas until the desired
554 branch revision is reached. Figure 5 illustrates a tree with
555 one side branch. Triangles pointing to the left and right represent
556 reverse and forward deltas, respectively.
560 define BD X [line invis $1 right .5;
561 line up .3 then left .5 down .3 then right .5 down .3 then up .3] X
563 define FD X [line invis $1 right .5;
564 line left .5 down .3 then up .6 then right .5 down .3;] X
568 arrow right from D11.e
570 arrow right from D12.e
572 arrow right from D13.e
574 arrow right from D21.e
576 line invis down from D21.s
578 arrow from D13.se to F1.w
579 arrow from F1.e right
585 Figure 5. A revision tree with reverse and forward deltas.
588 Although implementing fast check-out for the latest trunk revision,
589 this arrangement has the disadvantage that generation of other revisions
590 takes time proportional to the number of deltas applied. For example,
591 regenerating the branch tip in Figure 5 requires application of five
592 deltas (including the initial one). Since usage statistics show that
593 the latest trunk revision is the one that is retrieved in 95 per cent
594 of all cases (see the section on usage statistics), biasing check-out time
595 in favor of that revision results in significant savings.
596 However, careful implementation of the delta application process is
597 necessary to provide low retrieval overhead for other revisions, in
598 particular for branch tips.
600 There are several techniques for delta application.
601 The naive one is to pass each delta to a general-purpose text editor.
602 A prototype of RCS invoked the UNIX editor \fIed\fR both
603 for applying deltas and for expanding the identification markers.
604 Although easy to implement, performance was poor, owing to the
605 high start-up costs and excess generality of \fIed\fR. An intermediate
606 version of RCS used a special-purpose, stream-oriented editor.
607 This technique reduced the cost of applying a delta to the cost of
608 checking out the latest trunk revision. The reason for this behavior
609 is that each delta application involves a complete pass over
610 the preceding revision.
612 However, there is a much better algorithm. Note that the deltas are
613 line oriented and that most of the work of a stream editor involves
614 copying unchanged lines from one revision to the next. A faster
615 algorithm avoids unnecessary copying of character strings by using
617 A piece table is a one-dimensional array, specifying how a given
618 revision is `pieced together' from lines in the RCS file.
619 Suppose piece table \fIPT\dr\u\fR represents revision \fIr\fR.
620 Then \fIPT\dr\u[i]\fR contains the starting position of line \fIi\fR
622 Application of the next delta transforms piece table \fIPT\dr\u\fR
623 into \fIPT\dr+1\u\fR. For instance, a delete command removes a
624 series of entries from the piece table. An insertion command inserts
625 new entries, moving the entries following the insertion point further down the
626 array. The inserted entries point to the text lines in the delta.
627 Thus, no I/O is involved except for reading the delta itself. When all
628 deltas have been applied to the piece table, a sequential pass
629 through the table looks up each line in the RCS file and copies it to
630 the output file, updating identification markers at the same time.
631 Of course, the RCS file must permit random access, since the copied
632 lines are scattered throughout that file. Figure 6 illustrates an
633 RCS file with two revisions and the corresponding piece tables.
637 \fIFigure 6 is not available.\fP
640 Figure 6. An RCS file and its piece tables
643 The piece table approach has the property that the time for applying a single
644 delta is roughly determined by the size of the delta, and not by the
645 size of the revision. For example, if a delta is
646 10 per cent of the size of a revision, then applying it takes only
647 10 per cent of the time to generate the latest trunk revision. (The stream
648 editor would take 100 per cent.)
650 There is an important alternative for representing deltas that affects
651 performance. SCCS\u3\d,
652 a precursor of RCS, uses \fIinterleaved\fR deltas.
653 A file containing interleaved deltas is partitioned into blocks of lines.
654 Each block has a header that specifies to which revision(s) the block
655 belongs. The blocks are sorted out in such a way that a single
656 pass over the file can pick up all the lines belonging to a given
657 revision. Thus, the regeneration time for all revisions is the same:
658 all headers must be inspected, and the associated blocks either copied
659 or skipped. As the number of revisions increases, the cost of retrieving
660 any revision is much higher than the cost of checking out the
661 latest trunk revision with reverse deltas. A detailed comparison
662 of SCCS's interleaved deltas and RCS's reverse deltas can be found
664 This reference considers the version of RCS with the
665 stream editor only. The piece table method improves performance
666 further, so that RCS is always faster than SCCS, except if 10
667 or more deltas are applied.
669 Additional speed-up for both delta methods can be obtained by caching
670 the most recently generated revision, as has been implemented in DSEE.\u5\d
671 With caching, access time to frequently used revisions can approach normal file
672 access time, at the cost of some additional space.
674 Locking: A Controversial Issue
676 The locking mechanism for RCS was difficult to design.
677 The problem and its solution are first presented in their `pure' form,
678 followed by a discussion of the complications
679 caused by `real-world' considerations.
681 RCS must prevent two or more persons from depositing competing changes of the
683 Suppose two programmers check out revision 2.4 and
684 modify it. Programmer A checks in a revision before programmer B\&.
685 Unfortunately, programmer B has not seen A's
686 changes, so the effect is that A's changes are covered up by B's deposit.
687 A's changes are not lost since all revisions
688 are saved, but they are confined to a single revision.\(dd
690 Note that this problem is entirely different from the atomicity problem.
692 concurrent update operations on the same RCS file cannot be permitted,
693 because that may result in inconsistent data.
694 Atomic updates are essential (and implemented in RCS),
695 but do not solve the conflict discussed here.
698 This conflict is prevented in RCS by locking.
699 Whenever someone intends to edit a revision (as opposed
700 to reading or compiling it), the revision should be checked out
702 using the \fI\-l\fR option on \fIco\fR. On subsequent check-in,
703 \fIci\fR tests the lock and then removes it.
704 At most one programmer at a time may
705 lock a particular revision, and only this programmer may check in
706 the succeeding revision.
707 Thus, while a revision is locked, it is the exclusive responsibility
710 An important maxim for software tools like RCS is that they must
711 not stand in the way of making progress with a project.
712 This consideration leads to several weakenings of the locking mechanism.
713 First of all, even if a revision is locked, it can
714 still be checked out. This is necessary if other people
715 wish to compile or inspect the locked revision
716 while the next one is in preparation. The only operations they
717 cannot do are to lock the revision or to check in the succeeding one. Secondly,
718 check-in operations on other branches in the RCS file are still possible; the
719 locking of one revision does not affect any other revision.
720 Thirdly, revisions are occasionally locked for a long period of time
721 because a programmer is absent or otherwise unable to complete
722 the assignment. If another programmer has to make a pressing change,
723 there are the following three alternatives for making progress:
724 a) find out who is holding the lock and ask that person to release it;
725 b) check out the locked revision, modify it, check it
726 in on a branch, and merge the changes later;
727 c) break the lock. Breaking a lock leaves a highly visible
728 trace, namely an electronic mail message that is sent automatically to the
729 holder of the lock, recording the breaker and a commentary requested from him.
730 Thus, breaking locks is tolerated under certain circumstances,
731 but will not go unnoticed.
732 Experience has shown that the automatic mail message attaches a high enough
733 stigma to lock breaking,
734 such that programmers break locks only in real emergencies,
735 or when a co-worker resigns and leaves locked revisions behind.
737 If an RCS file is private, i.e., when a programmer owns an RCS file
738 and does not expect anyone else to perform check-in operations,
739 locking is an unnecessary nuisance.
741 the `strict locking feature' discussed earlier may be disabled,
742 provided that file protection
743 is set such that only the owner may write the RCS file.
744 This has the effect that only the owner can check-in revisions,
745 and that no lock is needed for doing so.
748 each RCS file contains an access list that specifies the users
749 who may execute update operations. If an access list is empty,
750 only normal UNIX file protection applies. Thus, the access list is
751 useful for restricting the set of people who would otherwise have update
752 permission. Just as with locking, the access list
753 has no effect on read-only operations such as \fIco\fR. This approach
754 is consistent with the UNIX philosophy of openness, which contributes
755 to a productive software development environment.
757 Configuration Management
759 The preceding sections described how RCS deals with revisions of individual
760 components; this section discusses how to handle configurations.
761 A configuration is a set of revisions, where each revision comes
762 from a different revision group, and the revisions are selected
763 according to a certain criterion.
765 in order to build a functioning compiler, the `right'
766 revisions from the scanner, the parser, the optimizer
767 and the code generator must be combined.
768 RCS, in conjunction with MAKE,
769 provides a number of facilities to effect a smooth selection.
771 RCS Selection Functions
773 .IP "\fIDefault selection\fR"
775 During development, the usual selection criterion is to choose
776 the latest revision of all components. The \fIco\fR command
777 makes this selection by default. For example, the command
781 retrieves the latest revision on the default branch of each RCS file
782 in the current directory.
783 The default branch is usually the trunk, but may be
784 set to be a side branch.
785 Side branches as defaults are needed in distributed software development,
786 as discussed in the section on the RCS revision tree.
788 .IP "\fIRelease based selection\fR"
790 Specifying a release or branch number selects the latest revision in
791 that release or branch.
796 retrieves the latest revision with release number 2 from each RCS file.
797 This selection is convenient if a release has been completed and
798 development has moved on to the next release.
800 .IP "\fIState and author based selection\fR"
802 If the highest level number within a given release number
803 is not the desired one,
804 the state attribute can help. For example,
806 co \-r2 \-sReleased *,v
808 retrieves the latest revision with release number 2 whose state attribute
810 Of course, the state attribute has to be set appropriately, using the
811 \fIci\fR or \fIrcs\fR commands.
812 Another alternative is to select a revision by its author,
813 using the \fI\-w\fR option.
815 .IP "\fIDate based selection\fR"
817 Revisions may also be selected by date.
818 Suppose a release of an entire system was
819 completed and current on March 4, at 1:00 p.m. local time. Then the command
821 co \-d'March 4, 1:00 pm LT' *,v
823 checks out all the components of that release, independent of the numbering.
824 The \fI\-d\fR option specifies a `cutoff date', i.e.,
825 the revision selected has a check-in date that
826 is closest to, but not after the date given.
827 .IP "\fIName based selection\fR"
829 The most powerful selection function is based on assigning symbolic
830 names to revisions and branches.
831 In large systems, a single release number or date is not sufficient
832 to collect the appropriate revisions from all groups.
833 For example, suppose one wishes to combine release 2
834 of one subsystem and release 15 of another.
835 Most likely, the creation dates of those releases differ also.
836 Thus, a single revision number or date passed to the \fIco\fR command
837 will not suffice to select the right revisions.
838 Symbolic revision numbers solve this problem.
839 Each RCS file may contain a set of symbolic names that are mapped
840 to numeric revision numbers. For example, assume
841 the symbol \fIV3\fR is bound to release number 2 in file \fIs,v\fR, and to
842 revision number 15.9 in \fIt,v\fR.
843 Then the single command
847 retrieves the latest revision of release 2 from \fIs,v\fR,
848 and revision 15.9 from \fIt,v\fR.
849 In a large system with many modules, checking out all
850 revisions with one command greatly simplifies configuration management.
852 Judicious use of symbolic revision numbers helps with organizing
853 large configurations.
854 A special command, \fIrcsfreeze\fR,
855 assigns a symbolic revision number to a selected revision
857 \fIRcsfreeze\fR effectively freezes a configuration.
858 The assigned symbolic revision number selects all components
859 of the configuration.
860 If necessary, symbolic numbers
861 may even be intermixed with numeric ones. Thus, \fIV3.5\fR in the
863 would select revision 2.5 in \fIs,v\fR and branch 15.9.5 in \fIt,v\fR.
865 The options \fI\-r\fR, \fI\-s\fR, \fI\-w\fR and \fI\-d\fR
866 may be combined. If a branch is given, the latest revision
867 on that branch satisfying all conditions is retrieved;
868 otherwise, the default branch is used.
870 Combining MAKE and RCS
873 is a program that processes configurations.
874 It is driven by configuration specifications
875 recorded in a special file, called a `Makefile'.
876 MAKE avoids redundant processing steps
877 by comparing creation dates of source and processed objects.
878 For example, when instructed to compile all
879 modules of a given system, it only recompiles
880 those source modules that were changed
881 since they were processed last.
883 MAKE has been extended with an auto-checkout feature for RCS.*
885 This auto-checkout extension is available only in some versions of MAKE,
888 When a certain file to be processed is not present,
889 MAKE attempts a check-out operation.
890 If successful, MAKE performs the required processing, and then deletes
891 the checked out file to conserve space.
892 The selection parameters discussed above can be passed to MAKE
893 either as parameters, or directly embedded in the Makefile.
894 MAKE has also been extended to search the subdirectory named \fIRCS\fR
895 for needed files, rather than just the current working directory.
896 However, if a working file is present, MAKE totally ignores the corresponding
897 RCS file and uses the working file.
898 (In newer versions of MAKE distributed by AT&T and others,
900 achieved with the rule DEFAULT, instead of a special extension of MAKE.
901 However, a file checked out by the rule DEFAULT
902 will not be deleted after processing. \fIRcsclean\fR can be
903 used for that purpose.)
905 With auto-checkout, RCS/MAKE can effect a selection rule
906 especially tuned for multi-person software development and maintenance.
908 programmers should obtain configurations that consist of
909 the revisions they have personally checked out plus the latest
910 checked in revision of all other revision groups.
911 This schema can be set up as follows.
913 Each programmer chooses a working directory
914 and places into it a symbolic link, named \fIRCS\fR,
915 to the directory containing the relevant RCS files.
916 The symbolic link makes sure that \fIco\fR and \fIci\fR
917 operations need only specify the working files, and that
918 the Makefile need not be changed.
919 The programmer then checks out the needed files and modifies them.
921 it composes configurations by selecting those
922 revisions that are checked out, and the rest from the
923 subdirectory \fIRCS\fR.
924 The latter selection may be controlled by a symbolic
925 revision number or any of the other selection criteria.
926 If there are several programmers editing in separate working directories,
927 they are insulated from each other's changes until checking in their
930 Similarly, a maintainer can recreate an older configuration
931 by starting to work in an empty working directory.
932 During the initial MAKE invocation, all revisions are selected from RCS files.
933 As the maintainer checks out files and modifies them,
934 a new configuration is gradually built up.
935 Every time MAKE is invoked, it substitutes the modified revisions
936 into the configuration being manipulated.
938 A final application of RCS is to use it for storing Makefiles.
939 Revision groups of Makefiles represent
940 multiple versions of configurations.
941 Whenever a configuration is baselined or distributed,
942 the best approach is to unambiguously fix
943 the configuration with a symbolic revision number by calling
945 to embed that symbol into the Makefile, and to
946 check in the Makefile (using the same symbolic revision number).
947 With this approach, old configurations
948 can be regenerated easily and reliably.
952 The following usage statistics were collected on two DEC VAX-11/780
953 computers of the Purdue Computer Science Department. Both machines
954 are mainly used for research purposes. Thus, the data
955 reflect an environment in which the majority of projects
956 involve prototyping and advanced software development,
957 but relatively little long-term maintenance.
959 For the first experiment,
960 the \fIci\fR and \fIco\fR operations were instrumented
961 to log the number of backward and forward deltas applied.
962 The data were collected during a 13 month period
963 from Dec. 1982 to Dec. 1983.
964 Table I summarizes the results.
973 Operation#Total#Total deltas#Mean deltas#Operations#Branch
974 #operations #applied#applied#with >1 delta#operations
976 co # 7867# 9320#1.18#509#(6%)#203#(3%)
977 ci # 3468# 2207#0.64# 85#(2%)# 75#(2%)
978 ci & co#11335#11527#1.02#594#(5%)#278#(2%)
981 Table I. Statistics for \fIco\fR and \fIci\fR operations.
985 The first two lines show statistics for check-out and check-in;
986 the third line shows the combination.
987 Recall that \fIci\fR performs an implicit check-out to obtain
988 a revision for computing the delta.
989 In all measures presented, the most recent revision (stored intact)
990 counts as one delta. The number of deltas applied represents
991 the number of passes necessary, where the first `pass' is a copying step.
993 Note that the check-out operation is executed more than
994 twice as frequently as the check-in operation.
995 The fourth column gives the mean number of deltas
996 applied in all three cases.
997 For \fIci\fR, the mean number of deltas applied is less
999 The reasons are that the initial check-in requires no delta at all, and that
1000 the only time \fIci\fR requires more than one delta is for branches.
1001 Column 5 shows the actual number of operations that applied more than one
1003 The last column indicates that branches were not used often.
1005 The last three columns demonstrate that the most recent trunk revision
1006 is by far the most frequently accessed.
1007 For RCS, check-out of
1008 this revision is a simple copy operation, which is the absolute minimum
1009 given the copy-semantics of \fIco\fR.
1010 Access to older revisions and branches
1011 is more common in non-academic environments,
1012 yet even if access to older deltas were an order
1013 of magnitude more frequent,
1014 the combined average number of deltas applied would still be below 1.2.
1015 Since RCS is faster than SCCS until up to 10 delta applications,
1016 reverse deltas are clearly the method of choice.
1018 The second experiment, conducted in March of 1984,
1019 involved surveying the existing RCS files
1020 on our two machines. The goal was to determine the mean number of
1021 revisions per RCS file, as well as the space consumed by them.
1022 Table II shows the results. (Tables I and II were produced at different
1023 times and are unrelated.)
1029 c | c | c | c | c | c | c
1030 c | c | c | c | c | c | c
1031 l | n | n | n | n | n | n.
1032 #Total RCS#Total#Mean#Mean size of#Mean size of#Overhead
1033 #files#revisions#revisions#RCS files#revisions
1035 All files #8033#11133#1.39#6156#5585#1.10
1036 Files with#1477# 4578#3.10#8074#6041#1.34
1040 Table II. Statistics for RCS files.
1044 The mean number of revisions per RCS file is 1.39.
1045 Columns 5 and 6 show the mean sizes (in bytes) of an RCS file
1046 and of the latest revision of each RCS file, respectively.
1047 The `overhead' column contains the ratio of the mean sizes.
1048 Assuming that all revisions in an RCS file are approximately the same size,
1049 this ratio gives a measure of the space consumed by the extra revisions.
1051 In our sample, over 80 per cent of the RCS files contained only a single revision.
1052 The reason is that our
1053 systems programmers routinely check in all source files
1054 on the distribution tapes, even though they may never touch them again.
1055 To get a better indication of how much space savings are possible
1056 with deltas, all measures with those files
1057 that contained 2 or more revisions were recomputed. Only for those files
1059 As shown in the second line, the average number of revisions for those files is
1060 3.10, with an overhead of 1.34. This means that the extra 2.10 deltas
1061 require 34 per cent extra space, or
1062 16 per cent per extra revision.
1064 measured the space consumed by SCCS, and
1065 reported an average of 5 revisions per group
1066 and an overhead of 1.37 (or about 9 per cent per extra revision).
1067 In a later paper, Glasser\u6\d
1068 observed an average of 7 revisions per group in a single, large project,
1069 but provided no overhead figure.
1070 In his paper on DSEE\u5\d,
1071 Leblang reported that delta storage combined with blank compression
1072 results in an overhead of a mere 1\-2 per cent per revision.
1073 Since leading blanks accounted for about 20 per cent of the surveyed Pascal
1074 programs, a revision group with 5\-10 members was smaller
1075 than a single cleartext copy.
1077 The above observations demonstrate clearly that the space needed
1078 for extra revisions is small. With delta storage, the luxury of
1079 keeping multiple revisions online is certainly affordable.
1080 In fact, introducing a system with delta storage may reduce
1081 storage requirements, because programmers often save back-up copies
1082 anyway. Since back-up copies are stored much more efficiently with deltas,
1083 introducing a system such as RCS may
1084 actually free a considerable amount of space.
1086 Survey of Version Control Tools
1088 The need to keep back-up copies of software arose when
1089 programs and data were no longer stored on paper media, but were entered
1090 from terminals and stored on disk.
1091 Back-up copies are desirable for reliability, and many modern editors
1092 automatically save a back-up copy for every file touched.
1094 is valuable for short-term back-ups, but not suitable for long-term
1095 version control, since an existing back-up copy is overwritten whenever the
1096 corresponding file is edited.
1098 Tape archives are suitable for long-term, offline storage.
1099 If all changed files are dumped on a back-up tape once per day, old revisions
1100 remain accessible. However, tape archives are unsatisfactory
1101 for version control in several ways. First, backing up the file
1102 system every 24 hours does not capture intermediate revisions.
1103 Secondly, the old revisions are not online,
1104 and accessing them is tedious and time-consuming.
1105 In particular, it is impractical to
1106 compare several old revisions of a group,
1107 because that may require mounting and searching several tapes.
1108 Tape archives are important fail-safe tools in the
1109 event of catastrophic disk failures or accidental deletions,
1110 but they are ill-suited for version control.
1111 Conversely, version control tools do not obviate the
1112 need for tape archives.
1114 A natural technique for keeping several old revisions online is
1115 to never delete a file.
1117 simply creates a new file with the same
1118 name, but with a different sequence number.
1119 This technique, available as an option in DEC's VMS operating system,
1120 turns out to be inadequate for version control.
1121 First, it is prohibitively expensive in terms of storage costs,
1122 especially since no data compression techniques are employed.
1123 Secondly, indiscriminately storing every change produces too many
1124 revisions, and programmers have difficulties distinguishing them.
1125 The proliferation of revisions forces programmers to spend much time on
1126 finding and deleting useless files.
1127 Thirdly, most of the support functions like locking, logging,
1129 and identification described in this paper are not available.
1131 An alternative approach is to separate editing from revision control.
1132 The user may repeatedly edit a given revision,
1133 until freezing it with an explicit command.
1134 Once a revision is frozen, it is stored permanently and can no longer be modified.
1135 (In RCS, freezing a revisions is done with \fIci\fR.)
1136 Editing a frozen revision implicitly creates a new one, which
1137 can again be changed repeatedly until it is frozen itself.
1138 This approach saves exactly those revisions that the user
1139 considers important, and keeps the number of revisions manageable.
1140 IBM's CLEAR/CASTER\u7\d,
1144 are examples of version control systems using this approach.
1145 CLEAR/CASTER maintains a data base of programs, specifications,
1146 documentation and messages, using deltas.
1147 Its goal is to provide control over the development process from a
1148 management viewpoint.
1149 SCCS stores multiple revisions of source text in an ancestral tree,
1150 records a log entry for each revision,
1151 provides access control, and has facilities
1152 for uniquely identifying each revision.
1153 An efficient delta technique
1154 reduces the space consumed by each revision group.
1155 SDC is much simpler than SCCS because it stores not more than
1156 two revisions. However, it maintains a complete log for all old
1157 revisions, some of which may be on back-up tape.
1158 CMS, like SCCS, manages tree-structured revision groups,
1159 but offers no identification mechanism.
1161 Tools for dealing with configurations are still in a state of flux.
1162 SCCS, SDC and CMS can be combined with MAKE or MAKE-like programs.
1163 Since flexible selection rules are missing from all these tools,
1164 it is sometimes difficult
1165 to specify precisely which revision of each group
1166 should be passed to MAKE for building a desired configuration.
1167 The Xerox Cedar system\u10\d
1168 provides a `System Modeller' that can rebuild
1169 a configuration from an arbitrary set of module revisions.
1170 The revisions of a module are only distinguished by creation time,
1171 and there is no tool for managing groups.
1172 Since the selection rules are primitive,
1173 the System Modeller appears to be somewhat tedious to use.
1175 is a sophisticated software engineering environment.
1176 It manages revision groups in a way similar to SCCS and CMS. Configurations
1177 are built using `configuration threads'.
1178 A configuration thread states which revision of each group
1179 named in a configuration should be chosen.
1180 A configuration thread may contain dynamic specifiers
1181 (e.g., `choose the revisions I am currently working on,
1182 and the most recent revisions otherwise'), which are bound
1183 automatically at build time.
1184 It also provides a notification mechanism for alerting
1185 maintainers about the need to rebuild a system after a change.
1187 RCS is based on a general model for describing
1188 multi-version/multi-configuration systems\u11\d.
1189 The model describes systems using AND/OR graphs, where AND nodes represent
1190 configurations, and OR nodes represent version groups.
1191 The model gives rise to a suit of selection rules for
1192 composing configurations, almost all of which are implemented in RCS.
1193 The revisions selected by RCS are passed to MAKE for configuration building.
1194 Revision group management is modelled after SCCS.
1195 RCS retains SCCS's best features,
1196 but offers a significantly simpler user interface,
1197 flexible selection rules, adequate integration with MAKE
1198 and improved identification.
1199 A detailed comparison of RCS and SCCS appears in Reference 4.
1201 An important component of all revision control systems
1202 is a program for computing deltas.
1203 SCCS and RCS use the program \fIdiff\fR\u2\d,
1204 which first computes the longest common substring of two
1205 revisions, and then produces the delta from that substring.
1206 The delta is simply an edit script consisting of deletion and
1207 insertion commands that generate one revision from the other.
1209 A delta based on a longest common substring is not necessarily minimal,
1210 because it does not take advantage of crossing block moves.
1211 Crossing block moves arise if two or more blocks of lines
1213 appear in a different order in two revisions.
1214 An edit script derived from a longest common substring
1215 first deletes the shorter of the two blocks, and then reinserts it.
1217 proposed an algorithm for detecting block moves, but
1218 since the algorithm is based on heuristics,
1219 there are conditions
1220 under which the generated delta is far from minimal.
1221 DSEE uses this algorithm combined with blank compression,
1222 apparently with satisfactory overall results.
1223 A new algorithm that is guaranteed to produce a minimal delta based on
1224 block moves appears in Reference 13.
1225 A future release of RCS will use this algorithm.
1227 \fIAcknowledgements\fR:
1228 Many people have helped make RCS a success by contributed criticisms, suggestions,
1229 corrections, and even whole new commands (including manual pages).
1230 The list of people is too long to be
1231 reproduced here, but my sincere thanks for their help and
1232 goodwill goes to all of them.
1237 Appendix: Synopsis of RCS Operations
1239 .IP "\fIci\fP \fB\- check in revisions\fP"
1241 \fICi\fR stores the contents of a working file into the
1242 corresponding RCS file as a new revision.
1243 If the RCS file doesn't exist, \fIci\fR creates it.
1244 \fICi\fR removes the working file, unless one of the options
1245 \fI\-u\fR or \fI\-l\fR is present.
1246 For each check-in, \fIci\fR asks for a commentary
1247 describing the changes relative to the previous revision.
1249 \fICi\fR assigns the revision number given by the \fI\-r\fR option;
1250 if that option is missing, it derives the number from the
1251 lock held by the user; if there is no lock and locking is not strict,
1252 \fIci\fR increments the number of the latest revision on the trunk.
1253 A side branch can only be started by explicitly specifying its
1254 number with the \fI\-r\fR option during check-in.
1256 \fICi\fR also determines
1257 whether the revision to be checked in is different from the
1258 previous one, and asks whether to proceed if not.
1259 This facility simplifies check-in operations for large systems,
1260 because one need not remember which files were changed.
1262 The option \fI\-k\fR searches the checked in file for identification
1265 revision number, check-in date, author and state, and assigns these
1266 to the new revision rather than computing them. This option is
1267 useful for software distribution: Recipients of distributed software
1268 using RCS should check in updates with the \fI\-k\fR option.
1269 This convention guarantees that revision numbers, check-in dates,
1270 etc., are the same at all sites.
1271 .IP "\fIco\fP \fB\- check out revisions\fP"
1273 \fICo\fR retrieves revisions according to revision number,
1274 date, author and state attributes. It either places the revision
1275 into the working file, or prints it on the standard output.
1276 \fICo\fR always expands the identification markers.
1277 .IP "\fIident\fP \fB\- extract identification markers\fP"
1279 \fIIdent\fR extracts the identification markers expanded by \fIco\fR
1280 from any file and prints them.
1281 .IP "\fIrcs\fP \fB\- change RCS file attributes\fP"
1283 \fIRcs\fR is an administrative operation that changes access lists,
1284 locks, unlocks, breaks locks, toggles the strict-locking feature,
1285 sets state attributes and symbolic revision numbers, changes the
1286 description, and deletes revisions. A revision can
1287 only be deleted if it is not the fork of a side branch.
1290 .IP "\fIrcsclean\fP \fB\- clean working directory\fP"
1292 \fIRcsclean\fR removes working files that were checked out but never changed.*
1294 The \fIrcsclean\fP and \fIrcsfreeze\fP commands
1295 are optional and are not always installed.
1297 .IP "\fIrcsdiff\fP \fB\- compare revisions\fP"
1299 \fIRcsdiff\fR compares two revisions and prints their
1300 difference, using the UNIX tool \fIdiff\fR.
1301 One of the revisions compared may be checked out.
1302 This command is useful for finding out about changes.
1303 .IP "\fIrcsfreeze\fP \fB\- freeze a configuration\fP"
1305 \fIRcsfreeze\fR assigns the same symbolic revision number
1306 to a given revision in all RCS files.
1307 This command is useful for accurately recording a configuration.*
1308 .IP "\fIrcsmerge\fP \fB\- merge revisions\fP"
1310 \fIRcsmerge\fR merges two revisions, \fIrev1\fR and \fIrev2\fR,
1311 with respect to a common ancestor.
1312 A 3-way file comparison determines the segments of lines that
1313 are (a) the same in all three revisions, or (b) the same in 2 revisions,
1314 or (c) different in all three. For all segments of type (b) where
1315 \fIrev1\fR is the differing revision,
1316 the segment in \fIrev1\fR replaces the corresponding segment of \fIrev2\fR.
1317 Type (c) indicates an overlapping change, is flagged as an error, and requires user
1318 intervention to select the correct alternative.
1319 .IP "\fIrlog\fP \fB\- read log messages\fP"
1321 \fIRlog\fR prints the log messages and other information in an RCS file.
1331 .ds [A Feldman, Stuart I.
1333 .ds [T Make\*-A Program for Maintaining Computer Programs
1334 .ds [J Software\*-Practice & Experience
1342 .][ 1 journal-article
1346 .ds [T An Algorithm for Differential File Comparison
1347 .ds [A Hunt, James W.
1348 .as [A " and McIlroy, M. D.
1349 .ds [I Computing Science Technical Report, Bell Laboratories
1359 .ds [A Rochkind, Marc J.
1361 .ds [T The Source Code Control System
1362 .ds [J IEEE Transactions on Software Engineering
1370 .][ 1 journal-article
1374 .ds [T Design, Implementation, and Evaluation of a Revision Control System
1375 .ds [A Tichy, Walter F.
1376 .ds [B Proceedings of the 6th International Conference on Software Engineering
1377 .ds [I ACM, IEEE, IPS, NBS
1378 .ds [D September 1982
1384 .][ 3 article-in-book
1388 .ds [A Leblang, David B.
1389 .as [A " and Chase, Robert P.
1390 .ds [T Computer-Aided Software Engineering in a Distributed Workstation Environment
1391 .ds [O Proceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium
1392 .as [O " on Practical Software Development Environments.
1393 .ds [J SIGPLAN Notices
1402 .][ 1 journal-article
1408 .ds [A Glasser, Alan L.
1410 .ds [T The Evolution of a Source Code Control System
1411 .ds [J Software Engineering Notes
1416 .ds [O Proceedings of the Software Quality and Assurance Workshop.
1420 .][ 1 journal-article
1424 .ds [K IBMClearCaster
1427 .ds [T The Clear/Caster System
1428 .ds [J Nato Conference on Software Engineering, Rome
1432 .][ 1 journal-article
1437 .ds [A Habermann, A. Nico
1439 .ds [T A Software Development Control System
1440 .ds [I Technical Report, Carnegie-Mellon University, Department of Computer Science
1449 .ds [T Code Management System
1450 .ds [I Digital Equipment Corporation
1451 .ds [O Document No.\ EA-23134-82
1460 .ds [A Lampson, Butler W.
1461 .as [A " and Schmidt, Eric E.
1462 .ds [T Practical Use of a Polymorphic Applicative Language
1463 .ds [B Proceedings of the 10th Symposium on Principles of Programming Languages
1471 .][ 3 article-in-book
1476 .ds [T A Data Model for Programming Support Environments and its Application
1477 .ds [A Tichy, Walter F.
1478 .ds [B Automated Tools for Information System Design and Development
1479 .ds [E Hans-Jochen Schneider and Anthony I. Wasserman
1481 .ds [I North-Holland Publishing Company
1486 .][ 3 article-in-book
1492 .ds [T A Technique for Isolating Differences Between Files
1494 .ds [J Communications of the ACM
1503 .][ 1 journal-article
1507 .ds [T The String-to-String Correction Problem with Block Moves
1508 .ds [A Tichy, Walter F.
1510 .ds [J ACM Transactions on Computer Systems
1518 .][ 1 journal-article
projects / dragonfly.git / blob