NetBSD/share/doc/ps1/13.rcs/rcs.ms

.\" Copyright (c) 1986 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Walter Tichy.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)rcs.ms	6.2 (Berkeley) 4/17/91
.\"
.OH 'Introduction to RCS''PS1:13-%'
.EH 'PS1:13-%''Introduction to RCS'
.TL
An Introduction to the Revision Control System
.AU
Walter F. Tichy
.AI
Department of Computer Sciences
Purdue University
West Lafayette, IN 47907
.AB
The Revision Control System (RCS) manages software libraries.
It greatly increases programmer productivity
by centralizing and cataloging changes to a software project.
This document describes the benefits of using a source code control system.
It then gives a tutorial introduction to the use of RCS.
.AE
.SH
Functions of RCS
.PP
The Revision Control System (RCS) manages multiple revisions of text files.
RCS automates the storing, retrieval, logging, identification, and merging
of revisions. RCS is useful for text that is revised frequently, for example
programs, documentation, graphics, papers, form letters, etc.
It greatly increases programmer productivity
by providing the following functions.
.IP 1.
RCS stores and retrieves multiple revisions of program and other text.
Thus, one can maintain one or more releases while developing the next
release, with a minimum of space overhead. Changes no longer destroy the
original -- previous revisions remain accessible.
.RS
.IP a.
Maintains each module as a tree of revisions.
.IP b.
Project libraries can
be organized centrally, decentralized, or any way you like.
.IP c.
RCS works for any type of text: programs, documentation, memos, papers,
graphics, VLSI layouts, form letters, etc.
.RE
.IP 2.
RCS maintains a complete history of changes.
Thus, one can find out what happened to a module easily
and quickly, without having to compare source listings or
having to track down colleagues.
.RS
.IP a.
RCS performs automatic record keeping.
.IP b.
RCS logs all changes automatically.
.IP c.
RCS guarantees project continuity.
.RE
.IP 3.
RCS manages multiple lines of development.
.IP 4.
RCS can merge multiple lines of development.
Thus, when several parallel lines of development must be consolidated
into one line, the merging of changes is automatic.
.IP 5.
RCS flags coding conflicts.
If two or more lines of development modify the same section of code,
RCS can alert programmers about overlapping changes.
.IP 6.
RCS resolves access conflicts.
When two or more programmers wish to modify the same revision,
RCS alerts the programmers and makes sure that one change will not wipe
out the other one.
.IP 7.
RCS provides high-level retrieval functions.
Revisions can be retrieved according to ranges of revision numbers,
symbolic names, dates, authors, and states.
.IP 8.
RCS provides release and configuration control.
Revisions can be marked as released, stable, experimental, etc.
Configurations of modules can be described simply and directly.
.IP 9.
RCS performs automatic identification of modules with name, revision
number, creation time, author, etc.
Thus, it is always possible to determine which revisions of which
modules make up a given configuration.
.IP 10.
Provides high-level management visibility.
Thus, it is easy to track the status of a software project.
.RS
.IP a.
RCS provides a complete change history.
.IP b.
RCS records who did what when to which revision of which module.
.RE
.IP 11.
RCS is fully compatible with existing software development tools.
RCS is unobtrusive -- its interface to the file system is such that
all your existing software tools can be used as before.
.IP 12.
RCS' basic user interface is extremely simple. The novice only
needs to learn two commands. Its more sophisticated features have been
tuned towards advanced software development environments and the
experienced software professional.
.IP 13.
RCS simplifies software distribution if customers
also maintain sources with RCS. This technique assures proper
identification of versions and configurations, and tracking of customer
changes. Customer changes can be merged into distributed
versions locally or by the development group.
.IP 14.
RCS needs little extra space for the revisions (only the differences).
If intermediate revisions are deleted, the corresponding
differences are compressed into the shortest possible form.
.SH
Getting Started with RCS
.PP
Suppose you have a file f.c that you wish to put under control of RCS. 
Invoke the checkin command:
.DS
ci  f.c 
.DE
This command creates f.c,v, stores f.c into it as revision 1.1, and
deletes f.c.
It also asks you for a description. The description should be
a synopsis of the contents of the file.
All later checkin commands will ask you for a log entry,
which should summarize the changes that you made.
.PP
Files ending in ,v are called RCS files ("v" stands for "versions"),
the others are called working files.
To get back the working file f.c in the previous example, use the checkout
command:
.DS
co  f.c
.DE
This command extracts the latest revision from f.c,v and writes
it into f.c.
You can now edit f.c and check it in back in by invoking:
.DS
ci  f.c
.DE
\fICi\fR increments the revision number properly. 
If \fIci\fR complains with the message
.DS
        ci error: no lock set by <your login>
.DE
then your system administrator has decided to create all RCS files
with the locking attribute set to ``strict''.
With strict locking, you you must lock the revision during
the previous checkout. 
Thus, your last checkout should have been
.DS
co  -l  f.c
.DE
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.
Of course, it is too late now to do the checkout with locking, because you
probably modified f.c already, and a second checkout would
overwrite your changes. Instead, invoke
.DS
rcs  -l  f.c
.DE
This command will lock the latest revision for you, unless somebody
else got ahead of you already.
If someone else has the lock you will have to negotiate your changes
with them.
.PP
If your RCS file is private, i.e., 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 off the RCS file need not have a lock for checkin; all others
still do. Turning strict locking off and on is done with the commands:
.DS
rcs  -U  f.c       and         rcs  -L  f.c
.DE
You can set the locking to strict or non-strict on every RCS file.
.PP
If you do not want to clutter your working directory with RCS files, create 
a subdirectory called RCS in your working directory, and move all your RCS 
files there. RCS commands will look first into that directory to find 
needed files. All the commands discussed above will still work, without any 
change*. 
.FS
* Pairs of RCS and working files can really be specified in 3 ways: 
a) both are given, b) only the working file is given, c) only the
RCS file is given. Both files may have arbitrary path prefixes;
RCS commands pair them up intelligently.
.FE
.PP
To avoid the deletion of the working file during checkin (should you want to
continue editing), invoke
.DS
ci  -l  f.c
.DE
This command checks in f.c as usual, but performs an additional
checkout with locking.
Thus, it saves you one checkout operation.
There is also an option
\fB-u\fR for \fIci\fR that does a checkin followed by a checkout without
locking. This is useful if you want to compile the file after the checkin.
Both options also update the identification markers in your file (see below).
.PP
You can give \fIci\fR 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
.DS
ci  -r2  f.c       or          ci  -r2.1  f.c
.DE
assigns the number 2.1 to the new revision.
From then on, \fIci\fR will number the subsequent revisions
with 2.2, 2.3, etc. The corresponding \fIco\fR commands
.DS
co  -r2  f.c       and         co  -r2.1  f.c
.DE
retrieve the latest revision numbered 2.x and the revision 2.1,
respectively. \fICo\fR without a revision number selects
the latest revision on the "trunk", i.e., 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
.DS
		ci  -r1.3.1  f.c
.DE
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 \fIrcsfile\fR(5).
.SH
Automatic Identification
.PP
RCS can put special strings for identification into your source and object
code. To obtain such identification, place the marker
.DS
$Header: /cvsroot/src/share/doc/ps1/13.rcs/Attic/rcs.ms,v 1.1.1.1 1993/03/21 09:45:37 cgd Exp $
.DE
into your text, for instance inside a comment.
RCS will replace this marker with a string of the form
.DS
$Header: /cvsroot/src/share/doc/ps1/13.rcs/Attic/rcs.ms,v 1.1.1.1 1993/03/21 09:45:37 cgd Exp $
.DE
You never need to touch this string, because RCS keeps it
up to date automatically.
To propagate the marker into your object code, simply put
it into a literal character string. In C, this is done as follows:
.DS
static char rcsid[] = "$Header: /cvsroot/src/share/doc/ps1/13.rcs/Attic/rcs.ms,v 1.1.1.1 1993/03/21 09:45:37 cgd Exp $";
.DE
The command \fIident\fR extracts such markers from any file, even object code.
Thus, \fIident\fR helps you to find out 
which revisions of which modules were used in a given program. 
.PP
You may also find it useful to put the marker
.DS
$Log: rcs.ms,v $
Revision 1.1.1.1  1993/03/21 09:45:37  cgd
initial import of 386bsd-0.1 sources

.DE
into your text, inside a comment. This marker accumulates
the log messages that are requested during checkin.
Thus, you can maintain the complete history of your file directly inside it.
There are several additional identification markers; see \fIco\fR (1) for
details.
.SH
How to combine MAKE and RCS
.PP
If your RCS files are in the same directory as your working files,
you can put a default rule into your makefile. Do not use a rule
of the form .c,v.c, because such a rule keeps a copy of every
working file checked out, even those you are not working on. Instead, use this:
.DS

 .SUFFIXES: .c,v

 .c,v.o:
           co -q $*.c
           cc $(CFLAGS) -c $*.c
           rm -f $*.c

 prog:   f1.o f2.o .....
           cc f1.o f2.o ..... -o prog
.DE
This rule has the following effect. If a file f.c does not exist, and f.o 
is older than f.c,v, MAKE checks out f.c, compiles f.c into f.o, and then 
deletes f.c. 
From then on, MAKE will use f.o until you change f.c,v.
.PP
If f.c exists (presumably because you are working on it), the default
rule .c.o takes precedence, and f.c is compiled into f.o, but not deleted.
.PP
If you keep your RCS file in the directory ./RCS, all this will not work
and you have to write explicit checkout rules for every file, like
.DS
f1.c:   RCS/f1.c,v; co -q f1.c
.DE
Unfortunately, these rules do not
have the property of removing unneeded .c-files.
.SH
Additional Information on RCS
.PP
If you want to know more about RCS, for example how to work
with a tree of revisions and how to use symbolic revision numbers, read
the following paper:
.sp 1
Walter F. Tichy, ``Design, Implementation, and Evaluation of a
Revision Control System,'' in \fIProceedings of the 6th International
Conference on Software Engineering\fR, IEEE, Tokyo, Sept. 1982.
.PP
Taking a look at the manual page \fIRCSFILE\fP(5)
should also help to understand the revision tree permitted by RCS.