RCS(1) OpenBSD Reference Manual RCS(1)NAMErcs - RCS file management program
SYNOPSISrcs [-IiLqTUV] [-Aoldfile] [-ausers] [-b[rev]] [-cstring] [-e[users]]
[-kmode] [-l[rev]] [-mrev: msg] [-orev] [-tstr] [-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.
-tstr 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$ 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.
SEE ALSOci(1), co(1), ident(1), rcsclean(1), rcsdiff(1), rcsmerge(1), rlog(1)
Tichy, Walter F., "RCS -- a system for version control",
Software--Practice & Experience, 15:7, pp. 637-654, July, 1985.
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.
OpenBSD 4.9 September 3, 2010 OpenBSD 4.9
