rcsintro(1) CLIX rcsintro(1)
NAME
rcsintro - Introduction to Revision Control System (RCS) commands
DESCRIPTION
The Revision Control System (RCS) manages multiple revisions of text
files. The RCS automates the storing, retrieval, logging, identification,
and merging of revisions. The RCS is useful for text that is revised
frequently, such as programs, documentation, graphics, papers, and form
letters.
The novice user of the RCS needs to learn only two commands, ci and co.
The ci command, short for ``check in,'' 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. The co command, short for ``check
out,'' retrieves revisions from an RCS file.
Functions of RCS
This following list describes the many functions of the Revision Control
System.
Storage and retrieval of multiple revisions of text.
The RCS saves all old revisions in a space-efficient way. Changes
do not destroy the original, because the previous revisions remain
accessible. Revisions can be retrieved according to ranges of
revision numbers, symbolic names, dates, authors, and states.
Maintenance of a complete history of changes.
The RCS logs all changes automatically. In addition to the text of
each revision, the RCS stores the author, the date and time of
check-in, and a log message summarizing the change. The logging
procedure makes it easy to find out what happened to a module
without having to compare source listings or having to ask
colleagues.
Resolution of access conflicts.
When two or more people wish to modify the same revision, the RCS
alerts them and prevents one modification from corrupting the
other.
Maintenance of a tree of revisions.
The RCS can maintain separate lines of development for each module.
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 module can be merged. If
the revisions to be merged affect the same sections of code or
text, the RCS alerts the user about the overlapping changes.
2/94 - Intergraph Corporation 1
rcsintro(1) CLIX rcsintro(1)
Release and configuration control.
Revisions can be assigned symbolic names and marked as released,
stable, experimental, or anything the user chooses. With these
facilities, configurations of modules can be described simply and
directly.
creation time,
Automatic identification of each revision with name, revision number,
author, and other information.
The identification is like a stamp that can be embedded at an
appropriate place in the text of a revision. The identification
makes it simple to determine which revisions of which modules make
up a given configuration.
Minimization of secondary storage.
The RCS needs little extra space for the revisions since only the
differences are stored. If intermediate revisions are deleted, the
corresponding changes are compressed accordingly.
The RCS Procedure
Files are entered into the RCS with the ci command. This checkin command
creates the RCS file filename, stores the file as revision 1.1, and
deletes the original. It asks the user for a description. The
description may be a synopsis of the contents of the file. All subsequent
ci checkin commands will ask the user for a log entry, which may summarize
the changes the user made.
Files in the RCS directory are called ``RCS files.'' All other files are
called ``working files.''
To check out a file, use the co command. This command extracts the latest
revision from the RCS file and writes it into filename. The user may now
edit the file and check it back in by entering the ci command. The
revision number of the RCS file is incremented and the user is asked to
enter a log message describing the revision.
Locking Files
The locking of files allows only one user to check in an update, which is
especially useful if several people are working on one file. Even if a
file is locked, it can still be checked out for reading and compiling.
The locking of the file prevents anyone other than the user who locks the
file from checking in revisions.
Two types of locking are available: strict locking and unstrict locking.
With strict locking, a user needs to lock a file in order to check in
revisions. In unstrict locking, the owner of the RCS file does not need
to lock a file to check in revisions (other users still do).
For more information, see rcs(1).
2 Intergraph Corporation - 2/94
rcsintro(1) CLIX rcsintro(1)
Automatic Identification
The RCS can put special strings for identification into the source and
object code. To obtain such identification, place this marker in the
text:
$Id$
The RCS replaces this marker with a string of this form:
$Id: filename revision_number date time author state $
The user can always see with which revision number of the module with such
a marker. The RCS keeps the markers up to date automatically. To
propagate the markers into the object code, simply put them into literal
character strings. In C, this is done as follows:
static char rcsid[] = "$Id$";
The ident command extracts such markers from any file, even object code
and dumps. Thus, the ident command lets allows the user to see which
revisions of which modules were used in a given program.
The user may also find it useful to put the marker $Log$ into the text,
inside a comment. This marker accumulates the log messages that are
requested during checkin. Thus, a complete history of the file may be
maintained in the file itself.
There are several additional identification markers; see co(1) for
details.
Manipulating RCS Files
The user may want to avoid cluttering a working directory with RCS files.
To solve this problem, create a subdirectory called RCS in the working
directory, and move all of the RCS files to that directory. The RCS
commands check that directory first to find the needed files. (All RCS
commands will still work without any modification.)
To avoid the deletion of the working file during checkin (in case the user
wants to continue editing), use the ci command with the -l or -u flag.
This command checks in the as usual, but performs an implicit checkout.
The -l flag also locks the checked in revision; the -u flag does not.
Thus, these flags save the user one checkout operation. The -l flag is
used if locking is strict; the -u flag is used if locking is not strict.
Both update the identification markers in the working file.
The user may also change revision numbers, which may happen with a new
release. For example, assume all the revisions are numbered 1.1, 1.2,
1.3, and so on, and the user wants to start release 2. The ci command
with the -r flag assigns a new number, 2.1, to the new revision. From
2/94 - Intergraph Corporation 3
rcsintro(1) CLIX rcsintro(1)
then on, the ci command numbers the subsequent revisions as 2.2, 2.3, and
so on.
The co command, when used with the -r flag, retrieve the latest revision
numbered 2.x (or the specified revision, like 2.1). Entering co alone
selects the latest revision.
Managing Branches
The RCS tree is divided into ``trunks.'' A trunk is a group of revisions
with numbers consisting of two fields. The user may create ``branches,''
which are revisions with three fields (like revision 1.3.1). To start a
branch, enter the ci -r command. With the -r flag, enter the number of
the desired branch. For example, to start a branch at revision 1.3, enter
this command:
ci -r1.3.1 filename
This command starts a branch numbered 1 at revision 1.3, and assigns the
number 1.3.1 to the new revision of the filename file. For more
information about branches, see rcsfile(4).
RELATED INFORMATION
Commands: ci(1), co(1), ident(1), merge(1), rcs(1), rcsdiff(1),
rcsmerge(1), rlog(1)
Files: rcsfile(4)
Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision
Control System," in Proceedings of the 6th International Conference on
Software Engineering, IEEE, Tokyo, Sept. 1982
Walter F. Tichy, ``RCS--A System for Version Control,'' Software--
Practice & Experience, 15, 7 (July 1985), pp. 637-654.
4 Intergraph Corporation - 2/94