|RCS(1)||General Commands Manual||RCS(1)|
rcs — RCS file
Revision Control System (RCS) is a software tool which lets people manage multiple revisions of text that is revised frequently, such as source code or documentation.
rcs program is used to create RCS
files or manipulate the contents of existing files. A set of helper tools is
also available: specific revisions of files may be checked in or out, using
co(1); differences between revisions viewed
or merged, using rcsdiff(1) and
rcsmerge(1); and information about RCS
files and keyword strings displayed using
ident(1). See the respective manual pages
for more information about these utilities.
The following options are supported:
Files may be selected by revision or, where no
revision is specified, the latest revision of the default
branch is used. Revisions are specified either by using
-r option or by appending the revision number to
any option that supports it. Branches are selected using the
A file's revision consists of two elements: release number and level number. For example, revision 2.3 of a file denotes release 2, level 3. Levels may also be subdivided into sublevels: this might happen, for example, if a parallel development is forked from a lower level revision. The primary levels and the sublevels belong to separate branches: the primary levels belong to a branch called HEAD, while sublevels belong to branches specified by revision.
rcs also supports the notion of
state. The state is an arbitrary string of characters used
to describe a file (or a specific revision of a file). States can be set or
changed using the
-s option, for RCS tools which
support it. The state of a file/revision can be modified without having to
check in a new file/revision. The default state is ‘Exp’
(Experimental). Examples of states could be ‘Dev’,
‘Reviewed’, or ‘Stab’.
In order to make large groups of RCS files more manageable, RCS
tools have the ability to select files by their symbolic
name. Thus files can be selected by their symbolic name, rather than
numerical revision. ci(1)
-n are used to set
symbolic names for files.
The following methods of file selection are therefore available: revision number, state, and symbolic name. For options which take as argument rev or state, any of these methods may be used. Some examples:
$ co -r"myproject" foo.c $ rcs -m1.3:update foo.c $ ci -s"Exp" bar.c
As long as source files are edited inside a working directory,
their state can be determined using the
log commands, but as soon as files get exported from
a local working copy, it becomes harder to identify which revisions they
cvs(1) use a mechanism known as
‘keyword substitution’ to help identify the files. Embedded
strings of the form $keyword$ and $keyword:...$ in a file are replaced with
strings of the form $keyword: value$ whenever a new revision of the file is
obtained. The possible keywords are as follows:
Keyword substitution has its disadvantages: sometimes the literal
text string $Author$ is wanted inside a file without
rcs or cvs(1)
interpreting it as a keyword and expanding it. The
-ko option can be used to turn
off keyword substitution entirely though. There is unfortunately no way to
selectively turn off keyword substitution.
Each file and working directory copy of a file have a stored
default substitution mode. Substitution modes on files are set by the
The possible substitution modes are as follows:
-ko, but also avoids the conversion of line endings. This option is used to handle binary files.
diffand rcsdiff(1) commands to avoid displaying the differences between keyword substitutions.
-kkv, except that the locker's name is displayed along with the version if the given revision is currently locked. This option is normally not useful as
rcsand cvs(1) do not use file locking by default.
importcommand to guarantee that files that already contain external keywords do not get modified.
exportcommand to freeze the values before releasing software.
rcs utility exits 0 on success,
and >0 if an error occurs.
One of the most common uses of
rcs is to
track changes to a document containing source code.
As an example, we'll look at a user wishing to track source changes to a file foo.c.
If the RCS directory does not exist yet, create it as follows and invoke the check-in command:
$ mkdir RCS $ ci foo.c
This command creates an RCS file foo.c,v in the RCS directory, stores foo.c into it as revision 1.1, and deletes foo.c. ci(1) will prompt for a description of the file to be entered. Whenever a newly created (or updated) file is checked-in, ci(1) will prompt for a log message to be entered which should summarize the changes made to the file. That log message will be added to the RCS file along with the new revision.
The co(1) command can now be used to obtain a copy of the checked-in foo.c,v file:
$ co foo.c
This command checks the file out in unlocked mode. If a user wants
to have exclusive access to the file to make changes to it, it needs to be
checked out in locked mode using the
-l option of
the co(1) command. Only one concurrent locked
checkout of a revision is permitted.
Once changes have been made to the foo.c file, and before checking the file in, the rcsdiff(1) command can be used to view changes between the working file and the most recently checked-in revision:
$ rcsdiff -u foo.c
-u option produces a unified diff. See
diff(1) for more information.
Tichy, Walter F., RCS — a system for version control, Software — Practice & Experience, 15:7, pp. 637-654, July, 1985.
OpenRCS is compatible with Walter Tichy's original RCS implementation.
The flags [
-Mz] have no effect and are
provided for compatibility only.
The OpenRCS project is a BSD-licensed rewrite of the original Revision Control System and first appeared in OpenBSD 4.0.
OpenRCS was written by Jean-Francois Brousseau, Joris Vink, Niall O'Higgins, and Xavier Santolaria.
The original RCS code was written in large parts by Walter F. Tichy and Paul Eggert.
For historical reasons, the RCS tools do not permit whitespace between options and their arguments.
|March 16, 2018||OpenBSD-current|