<!doctype linuxdoc system>
<article>

<title> The RCS MINI-HOWTO
<author> Robert Kiesling
<date>v1.4, 14 August 1997

<abstract>
This document covers basic installation and usage of RCS, the GNU
Revision Control System, under Linux.  It also covers the installation
of the <tt>diff(1)</tt> and <tt>diff3(1)</tt> utilities, which are
necessary for RCS to operate.  This document may be reproduced freely,
in whole or in part, provided that any usage of this document conforms
to the general copyright notice of the HOWTO series of the Linux
Documentation Project.  See the file COPYRIGHT for details.  Send all
complaints, suggestions, errata, and any miscellany to <htmlurl
url="mailto:kiesling@terracom.net" name = "kiesling@terracom.net">, so
I can keep this document as complete and up to date as possible.
</abstract>
<toc>
<sect>Overview of RCS.
<P>
RCS, the revision control system, is a suite of programs that tracks
changes in text files and controls shared access to files in work
group situations.  It is generally used to maintain source code
modules.  It lends itself to tracking revisions of document files as
well.

RCS was written by Walter F. Tichy and Paul Eggert.  The latest
version which has been ported to Linux is RCS Version 5.7.  There is
also a semi-official, threaded version available.  Much of the
information in this HOWTO is taken from the RCS man pages.

RCS includes the <tt>rcs(1)</tt> program, which controls RCS archive
file attributes, <tt>ci(1)</tt> and <tt>co(1)</tt>, which check files
in and out of RCS archives, <tt>ident(1)</tt>, which searches RCS
archives by keyword identifiers, <tt>rcsclean(1)</tt>, a program to
clean up files that are not being worked on or haven't changed,
<tt>rcsdiff(1)</tt>, which runs <tt>diff(1)</tt> to compare the
revisions, <tt>rcsmerge(1),</tt> which merges two RCS branches into a
single working file, and <tt>rlog(1),</tt> which prints RCS log
messages.

Files archived by RCS may be text of any format, or binary if the
<tt>diff</tt> program used to generate change files handles 8-bit
data.  Files may optionally include identification strings to aid in
tracking by <tt>ident(1)</tt>.  RCS uses the utilities
<tt>diff(1)</tt> and <tt>diff3(3)</tt> to generate the change files
between revisions.  A RCS archive consists of the initial revision of
a file, which is version 1.1, and a series of change files, one for
each revision.  Each time a file is checked out of an archive with
<tt>co(1)</tt>, edited, and checked back into the archive with
<tt>ci(1)</tt>, the version number is increased, for example, to 1.2,
1.3, 1.4, and so on for successive revisions.

The archives themselves commonly reside in a <tt>./RCS</tt>
subdirectory, although RCS has other options for archive storage.

For an overview of RCS, see the <tt>rcsintro(1)</tt> manual page.


<sect>System requirements.
<P>
RCS needs <tt>diff(1)</tt> and <tt>diff3(3)</tt> to generate the
context diff files between revisions.  The diff utilities suite needs
to be installed on your system, and when you install RCS, the software
will check for its presence.

Precompiled diffutils binaries are available at:
<verb>
ftp://sunsite.unc.edu/pub/Linux/utils/text/diffutils-2.6.bin.ELF.tar.gz
</verb>
and its mirror sites.  If you need to compile <tt>diff(1)</tt>, et
al., from source, it is located at:
<verb>
ftp://prep.ai.mit.edu/pub/gnu/diffutils-2.7.tar.gz
</verb>
and its mirror sites.

You will also need to have the ELF libraries installed on your system
if you want to install pre-built binaries.  See the ELF-HOWTO for
further details.


<sect>Compiling RCS from Source.
<P>
Get the source distribution of RCS Version 5.7.  It is available at
<verb>
ftp://sunsite.unc.edu/pub/Linux/devel/vc/rcs-5.7.src.tar.gz
</verb>
and its mirrors. After you have unpacked the archive into your source
tree, you need to configure RCS for your system.  This is done via the
<tt>configure</tt> script in the source directory, which you need to
execute first.  This will generate a <tt>Makefile</tt> and the
appropriate <tt>conf.sh</tt> for your system.  You can then type
<verb>
make install
</verb>
which will build the binaries.  At some point you may need to
<tt>su</tt> to root so the binaries can be installed in the
correct directories.


<sect>Creating and maintaining archives.
<P>
The program <tt>rcs(1)</tt> does the work or creating archives and
modifying their attributes.  A summary of <tt>rcs(1)</tt> options may
be found in the <tt>rcs(1)</tt> manual page.

The easiest way to create an archive is first to <tt>mkdir RCS</tt> in
the current directory, then initialize the archive with the
<verb>
rcs -i name_of_work_file
</verb>
command.  This creates and archive with the name <tt>./RCS/name_of_work_file,v</tt> and requests a text message
describing the archive, but it does not deposit any revisions in the
archive.  You can turn on or off strict archive locking with the
commands
<verb>
rcs -L name_of_work_file
</verb>
and
<verb>
rcs -U name_of_work_file
</verb>
respectively.  There are other options for controlling access to the
archive, setting its format, and setting revision numbers, which are
covered in the <tt>rcs(1)</tt> manual page.


<sect><tt>ci(1)</tt> and <tt>co(1)</tt>.
<P>
<tt>ci(1)</tt> and <tt>co(1)</tt> are the commands used to check
files in and out of their RCS archives.  The <tt>ci(1)</tt> command
may also be used to a check a file both in and out of an archive.  In
their simplest forms, <tt>ci(1)</tt> and <tt>co(1)</tt> take only the
name of the working file.
<verb>
ci name_of_work_file
</verb>
and
<verb>
co name_of_work_file
</verb>
The command form
<verb>
ci -l name_of_work_file
</verb>
checks in the file with locking enabled, and 
<verb>
co -l name_of_work_file
</verb>
<em>is performed automatically.</em> That is, <tt>ci -l</tt> checks
the file out again with locking enabled.
<verb>
ci -u name_of_work_file
</verb>
checks the file into the archive, and checks it out again with
locking disabled.  In all cases, the user is prompted for a log
message.  

<tt>ci(1)</tt> will also create a RCS archive if one does not exist
already.  

If you don't specify a revision, <tt>ci(1)</tt> increments the
version number of the last revision locked in the archive, and appends
the revised working file to it.  If you specify a revision on an
existing branch, it must be higher than the existing revision numbers.
<tt>ci(1)</tt> will also create a new branch if you specify the
revision of a branch which does not exist.  See the <tt>ci(1)</tt>
and <tt>co(1)</tt> man pages for details.

<tt>ci(1)</tt> and <tt>co(1)</tt> have various options for interactive
and non-interactive use.  Again, see the <tt>ci(1)</tt> and
<tt>co(1)</tt> man pages for details.

<sect>Revision histories.
<P>
The <tt>rlog(1)</tt> program provides information about the archive
file and the logs of each revision stored in it.  A command like
<verb>
rlog work_file_name 
</verb> 
will print the version history of the file, each revision's creation
date and <tt>userids</tt> of author and the person who locked the
file.  You can specify archive attributes and revision parameters to
view.


<sect>Including RCS data in working files.
<P>
<tt>co(1)</tt> maintains a list of keywords of the RCS database which
are expanded when the working file is checked out.  The keyword
<tt>&dollar;Id&dollar;</tt> in a document will expand to a string which
contains the file name, revision number, the date checked out, the
author, the revision status, and the locker, if any.  Including the
keyword <tt>&dollar;Log&dollar;</tt> will expand to the document's
revision history log.

These and other keywords may be used as search criteria of the RCS
archive.  See the <tt>ident(1)</tt> man page for further details.

<sect>RCS and <tt>emacs(1)</tt> Version Control.
<P>
The Version Control facility of <tt>emacs(1)</tt> works as a front end
to RCS.  This information applies specifically to Version 19.34 of GNU
Emacs, which is provided with the major Linux distributions.  When
editing a file with <tt>emacs(1)</tt> which is registered with RCS,
the command <tt>vc-toggle-read-only</tt> (bound to <tt>C-x C-q</tt> by
default) will check a file in to the emacs's Version Control, and then
into RCS.  Emacs will open a buffer where you can type a log message
to be included in the RCS log.  When you are finished typing a log
entry, type <tt>C-c C-c</tt> to terminate your input and proceed with
the check-in process.

If you have selected strict locking for the file with RCS, you must
re-lock the file for editing by <tt>emacs(1)</tt>.  You can check the
file out for emacs's Version Control with the command <tt>%</tt> in
buffer-menu mode.

For more information, see the GNU Emacs Manual and the Emacs info pages.

</article>
