RCS(1)                     OpenBSD Reference Manual                     RCS(1)

NAME
     rcs - RCS file management program

SYNOPSIS
     rcs [-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 revi-
     sions of files may be checked in or out, using ci(1) and co(1); differ-
     ences between revisions viewed or merged, using rcsdiff(1) and
     rcsmerge(1); and information about RCS files and keyword strings dis-
     played 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 val-
                 ues 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 stan-
                 dard 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.

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

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 num-
     ber.  For example, revision 2.3 of a file denotes release 2, level 3.
     Levels may also be subdivided into sublevels: this might happen, for ex-
     ample, 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' (Experimen-
     tal).  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 $key-
     word:...$ in a file are replaced with strings of the form $keyword: val-
     ue$ whenever a new revision of the file is obtained.  The possible key-
     words 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) interpret-
     ing 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 sub-
     stitution mode.  Substitution modes on files are set by the -kmode op-
     tion.

     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 them-
                selves 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.

EXAMPLES
     One of the most common uses of rcs is to track changes to a document con-
     taining 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.  On-
     ly 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 ALSO
     ci(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.7                      May 31, 2007                                5
