NAME

rcs — RCS file management program

SYNOPSIS

rcs

[-IiLqTUV] [-Aoldfile] [-ausers] [-b[rev]] [-cstring] [-e[users]] [-kmode] [-l[rev]] [-mrev:msg] [-orev] [-t[str]] [-u[rev]] [-xsuffixes] file ...

DESCRIPTION

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.

The 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 ci(1) and co(1); differences between revisions viewed or merged, using rcsdiff(1) and rcsmerge(1); and information about RCS files and keyword strings displayed using rlog(1) and ident(1). See the respective manual pages for more information about these utilities.

The following options are supported:

-Aoldfile

Append the access list of oldfile to the access list of the RCS files.

-ausers

Add the usernames specified in the comma-separated list users to the access list of the RCS files.

-b[rev]

Set the default branch (see below) to rev. If no argument is specified, the default branch is set to the highest numbered branch.

-cstring

Set comment leader to string. The comment leader specifies the comment character(s) for a file. This option is useful for compatibility with older RCS implementations only.

-e[users]

Remove the usernames specified in the comma-separated list users from the access list of the RCS files. If users is not specified, all users are removed from the access list.

-I

Interactive mode.

-i

Create and initialize a new RCS file. If the RCS file has no path prefix, try to first create it in the ./RCS subdirectory or, if that fails, in the current directory. Files created this way contain no revision.

-kmode

Specify the keyword substitution mode (see below).

-L

Enable strict locking on the RCS files.

-l[rev]

Lock revision rev on the RCS files.

-mrev:msg

Replace revision rev's log message with msg.

-orev

Delete one or more revisions. The specifications of the values or revisions are as follows:


rev: Specific revision.

rev1:rev2: Delete all revisions of a branch between rev1 and rev2.

rev1::rev2: Delete all revisions of a branch between rev1 and rev2 without deleting revisions rev1 and rev2.

:rev: Delete all revisions of the branch until revision rev.

rev:: Delete all revisions of the branch from revision rev until the last revision of the branch.

-q

Be quiet about reporting.

-T

Preserve the modification time of RCS files.

-t[str]

Change the descriptive text. The argument str is interpreted as the name of a file containing the descriptive text or, if prefixed with a ‘-’, the actual descriptive text itself. If no argument is used, the descriptive text is taken from standard input terminated by end-of-file or by a line containing the ‘.’ character by itself.

-U

Disable strict locking on the RCS files.

-u[rev]

Unlock revision rev on the RCS files.

-V

Print the program's version string and exit.

-xsuffixes

Specifies the suffixes for RCS files. Suffixes should be separated by the ‘/’ character.

BRANCHES AND REVISIONS

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 the -r option or by appending the revision number to any option that supports it. Branches are selected using the -b option.

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 and -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

KEYWORD SUBSTITUTION

As long as source files are edited inside a working directory, their state can be determined using the cvs(1) status or log commands, but as soon as files get exported from a local working copy, it becomes harder to identify which revisions they are.

rcs and 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:


$Author$: The name of the user who checked in the revision.

$Date$: The date and hour (UTC) the revision was checked in.

$Header$: Standard header containing the full pathname of the RCS file, the revision number, the date (UTC), the author and the state.

$Id$ and $OpenBSD$: The same content as $Header$ but without the path of the RCS file.

$Log$: The log message supplied during commit, preceded by a header containing the RCS filename, the revision number, the author, and the date (UTC).

$Mdocdate$: Produce a date of the form month name, day number, and year, suitable for the mdoc(7) “Dd” macro.

$Name$: The tag name used to check out the file.

$RCSfile$: The name of the RCS file, but without a path.

$Revision$: The revision number assigned to the revision.

$Source$: The full pathname of the RCS file.

$State$: The state assigned to the revision.

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 -kmode option.

The possible substitution modes are as follows:


-kb: Like -ko, but also avoids the conversion of line endings. This option is used to handle binary files.

-kk: Does not substitute the keywords. Useful with the cvs(1) diff and rcsdiff(1) commands to avoid displaying the differences between keyword substitutions.

-kkv: The default behaviour. Keywords are normally substituted i.e. $Revision$ becomes $Revision: 1.1 $.

-kkvl: Like -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 rcs and cvs(1) do not use file locking by default.

-ko: No substitutions are done. This option is often used with the cvs(1) import command to guarantee that files that already contain external keywords do not get modified.

-kv: Substitute the value of keywords instead of keywords themselves e.g. instead of $Revision$, only insert 1.1 and not $Revision: 1.1 $. This option must be used with care, as it can only be used once. It is often used with the cvs(1) export command to freeze the values before releasing software.

ENVIRONMENT


RCSINIT: If set, this variable should contain a list of space-delimited options that are prepended to the argument list.

EXIT STATUS

The rcs utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

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

The -u option produces a unified diff. See diff(1) for more information.

STANDARDS

OpenRCS is compatible with Walter Tichy's original RCS implementation.

The flags [-Mz] have no effect and are provided for compatibility only.

HISTORY

The OpenRCS project is a BSD-licensed rewrite of the original Revision Control System. OpenRCS is 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.

CAVEATS

For historical reasons, the RCS tools do not permit whitespace between options and their arguments.