The RCS MINI-HOWTO

Robert Kiesling

1. Overview of RCS.

2. System requirements.

3. Compiling RCS from Source.

4. Creating and maintaining archives.

5. ci(1) and co(1).

6. Revision histories.

7. Including RCS data in working files.

8. RCS and emacs(1) Version Control.

1. Overview of RCS.

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

Files archived by RCS may be text of any format, or binary if the diff program used to generate change files handles 8-bit data. Files may optionally include identification strings to aid in tracking by ident(1). RCS uses the utilities diff(1) and diff3(3) 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 co(1), edited, and checked back into the archive with ci(1), 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 ./RCS subdirectory, although RCS has other options for archive storage.

For an overview of RCS, see the rcsintro(1) manual page.

2. System requirements.

RCS needs diff(1) and diff3(3) 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:

ftp://sunsite.unc.edu/pub/Linux/utils/text/diffutils-2.6.bin.ELF.tar.gz

ftp://prep.ai.mit.edu/pub/gnu/diffutils-2.7.tar.gz

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.

3. Compiling RCS from Source.

Get the source distribution of RCS Version 5.7. It is available at

ftp://sunsite.unc.edu/pub/Linux/devel/vc/rcs-5.7.src.tar.gz

make install

4. Creating and maintaining archives.

The program rcs(1) does the work or creating archives and modifying their attributes. A summary of rcs(1) options may be found in the rcs(1) manual page.

The easiest way to create an archive is first to mkdir RCS in the current directory, then initialize the archive with the

rcs -i name_of_work_file

rcs -L name_of_work_file

rcs -U name_of_work_file

5. ci(1) and co(1).

ci(1) and co(1) are the commands used to check files in and out of their RCS archives. The ci(1) command may also be used to a check a file both in and out of an archive. In their simplest forms, ci(1) and co(1) take only the name of the working file.

ci name_of_work_file

co name_of_work_file

ci -l name_of_work_file

co -l name_of_work_file

ci -u name_of_work_file

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

If you don't specify a revision, ci(1) 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. ci(1) will also create a new branch if you specify the revision of a branch which does not exist. See the ci(1) and co(1) man pages for details.

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

6. Revision histories.

The rlog(1) program provides information about the archive file and the logs of each revision stored in it. A command like

rlog work_file_name 

7. Including RCS data in working files.

co(1) maintains a list of keywords of the RCS database which are expanded when the working file is checked out. The keyword $Id$ 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 $Log$ 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 ident(1) man page for further details.

8. RCS and emacs(1) Version Control.

The Version Control facility of emacs(1) 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 emacs(1) which is registered with RCS, the command vc-toggle-read-only (bound to C-x C-q 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 C-c C-c 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 emacs(1). You can check the file out for emacs's Version Control with the command % in buffer-menu mode.

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