rcs.ms

早期freebsd实现

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