284 lines
9.0 KiB
Groff
284 lines
9.0 KiB
Groff
.\" $NetBSD: rcsintro.1,v 1.2 2016/01/14 04:22:39 christos Exp $
|
|
.\"
|
|
.TH RCSINTRO 1 "" GNU
|
|
.SH NAME
|
|
rcsintro \- introduction to RCS commands
|
|
.SH DESCRIPTION
|
|
programs, documentation, graphics, papers, and form letters.
|
|
The Revision Control System (RCS) manages multiple revisions of files.
|
|
RCS automates the storing, retrieval, logging, identification, and merging
|
|
of revisions. RCS is useful for text that is revised frequently, for example
|
|
.PP
|
|
The basic user interface is extremely simple. The novice only needs
|
|
to learn two commands:
|
|
.BR ci (1)
|
|
and
|
|
.BR co (1).
|
|
.BR ci ,
|
|
short for \*(lqcheck in\*(rq, deposits the contents of a
|
|
file into an archival file called an RCS file. An RCS file
|
|
contains all revisions of a particular file.
|
|
.BR co ,
|
|
short for \*(lqcheck out\*(rq, retrieves revisions from an RCS file.
|
|
.SS "Functions of RCS"
|
|
.IP \(bu
|
|
Store and retrieve multiple revisions of text. RCS saves all old
|
|
revisions in a space efficient way.
|
|
Changes no longer 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.
|
|
.IP \(bu
|
|
Maintain a complete history of changes.
|
|
RCS logs all changes automatically.
|
|
Besides the text of each revision, RCS stores the author, the date and time of
|
|
check-in, and a log message summarizing the change.
|
|
The logging makes it easy to find out
|
|
what happened to a module, without having to compare
|
|
source listings or having to track down colleagues.
|
|
.IP \(bu
|
|
Resolve access conflicts. When two or more programmers wish to
|
|
modify the same revision, RCS alerts the programmers and prevents one
|
|
modification from corrupting the other.
|
|
.IP \(bu
|
|
Maintain a tree of revisions. RCS can maintain separate lines of development
|
|
for each module. It stores a tree structure that represents the
|
|
ancestral relationships among revisions.
|
|
.IP \(bu
|
|
Merge revisions and resolve conflicts.
|
|
Two separate lines of development of a module can be coalesced by merging.
|
|
If the revisions to be merged affect the same sections of code, RCS alerts the
|
|
user about the overlapping changes.
|
|
.IP \(bu
|
|
Control releases and configurations.
|
|
Revisions can be assigned symbolic names
|
|
and marked as released, stable, experimental, etc.
|
|
With these facilities, configurations of modules can be
|
|
described simply and directly.
|
|
.IP \(bu
|
|
Automatically identify each revision with name, revision number,
|
|
creation time, author, etc.
|
|
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.
|
|
.IP \(bu
|
|
Minimize secondary storage. RCS needs little extra space for
|
|
the revisions (only the differences). If intermediate revisions are
|
|
deleted, the corresponding deltas are compressed accordingly.
|
|
.SS "Getting Started with RCS"
|
|
Suppose you have a file
|
|
.B f.c
|
|
that you wish to put under control of RCS.
|
|
If you have not already done so, make an RCS directory with the command
|
|
.IP
|
|
.B "mkdir RCS"
|
|
.LP
|
|
Then invoke the check-in command
|
|
.IP
|
|
.B "ci f.c"
|
|
.LP
|
|
This command creates an RCS file in the
|
|
.B RCS
|
|
directory,
|
|
stores
|
|
.B f.c
|
|
into it as revision 1.1, and
|
|
deletes
|
|
.BR f.c .
|
|
It also asks you for a description. The description
|
|
should be a synopsis of the contents of the file. All later check-in
|
|
commands will ask you for a log entry, which should summarize the
|
|
changes that you made.
|
|
.PP
|
|
Files in the RCS directory are called RCS files;
|
|
the others are called working files.
|
|
To get back the working file
|
|
.B f.c
|
|
in the previous example, use the check-out
|
|
command
|
|
.IP
|
|
.B "co f.c"
|
|
.LP
|
|
This command extracts the latest revision from the RCS file
|
|
and writes
|
|
it into
|
|
.BR f.c .
|
|
If you want to edit
|
|
.BR f.c ,
|
|
you must lock it as you check it out with the command
|
|
.IP
|
|
.B "co \-l f.c"
|
|
.LP
|
|
You can now edit
|
|
.BR f.c .
|
|
.PP
|
|
Suppose after some editing you want to know what changes that you have made.
|
|
The command
|
|
.IP
|
|
.B "rcsdiff f.c"
|
|
.LP
|
|
tells you the difference between the most recently checked-in version
|
|
and the working file.
|
|
You can check the file back in by invoking
|
|
.IP
|
|
.B "ci f.c"
|
|
.LP
|
|
This increments the revision number properly.
|
|
.PP
|
|
If
|
|
.B ci
|
|
complains with the message
|
|
.IP
|
|
.BI "ci error: no lock set by " "your name"
|
|
.LP
|
|
then you have tried to check in a file even though you did not
|
|
lock it when you checked it out.
|
|
Of course, it is too late now to do the check-out with locking, because
|
|
another check-out would
|
|
overwrite your modifications. Instead, invoke
|
|
.IP
|
|
.B "rcs \-l f.c"
|
|
.LP
|
|
This command will lock the latest revision for you, unless somebody
|
|
else got ahead of you already. In this case, you'll have to negotiate with
|
|
that person.
|
|
.PP
|
|
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
|
|
.I "check-in"
|
|
by anybody but the locker.
|
|
.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 of the RCS file need not have a lock for check-in; all others
|
|
still do. Turning strict locking off and on is done with the commands
|
|
.IP
|
|
.BR "rcs \-U f.c" " and " "rcs \-L f.c"
|
|
.LP
|
|
If you don't want to clutter your working directory with RCS files, create
|
|
a subdirectory called
|
|
.B 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
|
|
modification.
|
|
(Actually, pairs of RCS and working files can be specified in three ways:
|
|
(a) both are given, (b) only the working file is given, (c) only the
|
|
RCS file is given. Both RCS and working files may have arbitrary path prefixes;
|
|
RCS commands pair them up intelligently.)
|
|
.PP
|
|
To avoid the deletion of the working file during check-in (in case you want to
|
|
continue editing or compiling), invoke
|
|
.IP
|
|
.BR "ci \-l f.c" " or " "ci \-u f.c"
|
|
.LP
|
|
These commands check in
|
|
.B f.c
|
|
as usual, but perform an implicit
|
|
check-out. The first form also locks the checked in revision, the second one
|
|
doesn't. Thus, these options save you one check-out operation.
|
|
The first form is useful if you want to continue editing,
|
|
the second one if you just want to read the file.
|
|
Both update the identification markers in your working file (see below).
|
|
.PP
|
|
You can give
|
|
.B ci
|
|
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
|
|
.IP
|
|
.BR "ci \-r2 f.c" " or " "ci \-r2.1 f.c"
|
|
.LP
|
|
assigns the number 2.1 to the new revision.
|
|
From then on,
|
|
.B ci
|
|
will number the subsequent revisions
|
|
with 2.2, 2.3, etc. The corresponding
|
|
.B co
|
|
commands
|
|
.IP
|
|
.BR "co \-r2 f.c" " and " "co \-r2.1 f.c"
|
|
.PP
|
|
retrieve the latest revision numbered
|
|
.RI 2. x
|
|
and the revision 2.1,
|
|
respectively.
|
|
.B co
|
|
without a revision number selects
|
|
the latest revision on the
|
|
.IR trunk ,
|
|
i.e. the highest
|
|
revision with a number consisting of two fields. Numbers with more than two
|
|
fields are needed for branches.
|
|
For example, to start a branch at revision 1.3, invoke
|
|
.IP
|
|
.B "ci \-r1.3.1 f.c"
|
|
.LP
|
|
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
|
|
.BR rcsfile (5).
|
|
.SS "Automatic Identification"
|
|
RCS can put special strings for identification into your source and object
|
|
code. To obtain such identification, place the marker
|
|
.IP
|
|
.B "$\&Id$"
|
|
.LP
|
|
into your text, for instance inside a comment.
|
|
RCS will replace this marker with a string of the form
|
|
.IP
|
|
.BI $\&Id: " filename revision date time author state " $
|
|
.LP
|
|
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 follows:
|
|
.IP
|
|
.ft 3
|
|
static char rcsid[] = \&"$\&Id$\&";
|
|
.ft
|
|
.LP
|
|
The command
|
|
.B ident
|
|
extracts such markers from any file, even object code
|
|
and dumps.
|
|
Thus,
|
|
.B ident
|
|
lets you find out
|
|
which revisions of which modules were used in a given program.
|
|
.PP
|
|
You may also find it useful to put the marker
|
|
.B $\&Log$
|
|
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
|
|
.BR co (1)
|
|
for
|
|
details.
|
|
.SH IDENTIFICATION
|
|
Author: Walter F. Tichy.
|
|
.br
|
|
Manual Page Revision: \*(Rv; Release Date: \*(Dt.
|
|
.br
|
|
Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
|
|
.br
|
|
Copyright \(co 1990, 1991, 1992, 1993 Paul Eggert.
|
|
.SH "SEE ALSO"
|
|
ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1)
|
|
.br
|
|
Walter F. Tichy,
|
|
RCS\(emA System for Version Control,
|
|
.I "Software\(emPractice \*[Am] Experience"
|
|
.BR 15 ,
|
|
7 (July 1985), 637-654.
|
|
.br
|