rcsintro(5)rcsintro(5)NAMErcsintro - description of RCS commands
DESCRIPTION
Revision Control System (RCS) automates the storing, retrieval, log‐
ging, identification, and merging of revisions of ASCII text files.
RCS is useful for managing files that are revised frequently.
Functions of RCS
· Storage and retrieval of revisions of text files. RCS saves revi‐
sions in a space-efficient way. Revisions can be retrieved by
ranges of revision numbers, symbolic names, dates, authors, and
states.
· Maintenance of a complete history of changes. RCS logs all
changes automatically. In addition to the text of each revision,
RCS stores the author, date and time of check-in, and a log mes‐
sage summarizing the change.
· Resolution of access conflicts. When two or more people try to
modify the same revision of a file, RCS alerts them and prevents
one modification from corrupting the other.
· Maintenance of a tree of revisions. RCS can maintain separate
lines of development for each file. It stores a tree structure
that represents the ancestral relationships among revisions.
· Merging of revisions and resolution of conflicts. Two separate
lines of development of a file can be coalesced by merging. If
the revisions to be merged affect the same lines of a file, RCS
flags the overlapping changes.
· Release and configuration control. Revisions can be assigned sym‐
bolic names and marked as released, stable, experimental, etc.
With these facilities, configurations of a file can be described
simply and directly.
· Automatic identification of each revision with file name, revision
number, creation time, author, etc. This identification is like a
stamp that can be embedded at an appropriate place in the text of
a revision. These stamps make it simple to determine which revi‐
sions of which files make up a given configuration.
· Minimization of secondary storage. RCS uses very little extra
space for revisions (only the differences are stored). If inter‐
mediate revisions are deleted, the remaining deltas are compressed
accordingly.
Getting Started with RCS
The basic user interface is extremely simple. The novice only needs to
learn two commands: and (see ci(1) and co(1)). short for deposits the
contents of a text file into an archival file called an RCS file. An
RCS file contains all revisions of a particular text file. short for
retrieves revisions from an RCS file.
Suppose you have a file that you wish to put under control of RCS.
Invoke the check-in command:
This command creates the RCS file stores into it as revision and
deletes It also asks you for a description. The description should be
a synopsis of the contents of the file. All subsequent check-in com‐
mands will ask for a log entry, which should summarize the changes that
were made.
Files with names ending with are called RCS files stands for "ver‐
sions"); all other files are presumed to be working files. To get back
the working file in the previous example, use the check-out command:
This command extracts the latest revision from and writes it into You
can now edit and check it back in by invoking:
increments the revision number properly. If complains with the mes‐
sage:
your system administrator has decided to create all RCS files with the
locking attribute set to "strict". In this case, you should have
locked the revision during the previous check-out. Your last check-out
should have been:
Of course, it is too late now to do the check-out with locking, because
you probably modified already, and a second check-out would overwrite
your modifications. Instead, invoke:
This command will lock the latest revision for you, unless somebody
else has already locked it. In that case, you will have to negotiate
with that person.
Locking assures that you, and only you, can check in the next update,
and avoids nasty problems if several people work on the same file.
Even if a revision is locked, it can still be checked out for reading,
compiling, etc. All that locking prevents is a check-in by anybody but
the locker.
If your RCS file is private, that is, if you are the only person who is
going to deposit revisions into it, strict locking is not needed and
you can turn it off. If strict locking is turned off, the owner of the
RCS file need not have a lock for check-in; all others still do. Turn‐
ing strict locking off and on is done with the commands:
and
If you do not want to clutter your working directory with RCS files,
create a subdirectory called in your working directory, and move all
your RCS files there. RCS commands will search that directory to find
needed files. All the commands discussed above will still work without
any modification.
To avoid the deletion of the working file during check-in (in case you
want to continue editing), invoke:
or
These commands check in as usual, but perform an implicit check-out.
The first form also locks the checked-in revision, the second one does
not. Thus, these options save you one check-out operation. The first
form is useful if locking is strict; the second one if not strict.
Both update the identification markers in your working file (see
below).
You can give the number you want assigned to a checked in revision.
Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., and you
would like to start release 2. The command:
or
assigns the number 2.1 to the new revision. From then on, will number
the subsequent revisions with 2.2, 2.3, etc. The corresponding com‐
mands:
and
retrieve the latest revision numbered 2.x and the revision 2.1, respec‐
tively. without a revision number selects the latest revision on the
"trunk"; that is, the highest revision with a number consisting of 2
fields. Numbers with more than 2 fields are needed for branches. For
example, to start a branch at revision 1.3, invoke:
This command starts a branch numbered 1 at revision 1.3, and assigns
the number 1.3.1.1 to the new revision. For more information about
branches, see rcsfile(4).
RCS File Naming and Location
RCS recognizes two kinds of files: RCS files (revision archives), and
working files. Working file names are defined by the RCS user, RCS
file names are generated by RCS by appending to the working file name.
Pairs of RCS files and working files can be specified in 3 ways:
· Both the RCS file and the working file are given. The RCS file
name is of the form and the working file name is of the form where
path1 and path2 are (possibly different or empty) paths and work‐
file is a file name.
· Only the RCS file is given. Then the working file is assumed to
be in the current directory and its name is derived from the name
of the RCS file by removing and the suffix
· Only the working file is given. Then the name of the RCS file is
derived from the name of the working file by removing and append‐
ing the suffix
If the RCS file name is omitted or specified without a path, RCS com‐
mands look for the RCS file in the directory (or the directory it
points to if it is a directory link), then in the current working
directory.
RCS Directory Links
RCS supports directory links. If a regular file named RCS exists in
the current working directory, RCS interprets the first line as a path
name to the directory where RCS files are stored. RCS can follow a
chain of up to ten directory links to reach the RCS directory.
Automatic Identification
RCS can put special strings for identification into your source and
object code. To obtain such identification, place the marker:
into your text, for instance inside a comment. RCS replaces this
marker with a string of the form:
With such a marker on the first page of each module, you can always see
with which revision you are working. RCS keeps the markers up-to-date
automatically. To propagate the markers into your object code, simply
put them into literal character strings. In C, this is done as fol‐
lows:
The command extracts such markers from any file, even object code and
dumps. Thus, lets you find out which revisions of which modules were
used in a given program.
You may also find it useful to put the marker into your text, inside a
comment. This marker accumulates the log messages that are requested
during check-in. Thus, you can maintain the complete history of your
file directly inside it. There are several additional identification
markers. See co(1) for details.
WARNINGS
Names of RCS files are generated by appending to the end of the working
file name. If the resulting RCS file name is too long for the file
system on which the RCS file should reside, the RCS command terminates
with an error message.
RCS is designed to be used with TEXT files only. Attempting to use RCS
with nontext (binary) files will result in data corruption.
AUTHOR
was developed by Walter F. Tichy, Purdue University, West Lafayette, IN
47907, USA.
1982 by Walter F. Tichy.
SEE ALSOci(1), co(1), ident(1), merge(1), rcs(1), rcsdiff(1), rcsmerge(1),
rlog(1), rcsfile(4).
"Design, Implementation, and Evaluation of a Revision Control System,"
by Walter F. Tichy, in IEEE, Tokyo, September 1982.
rcsintro(5)
