path: root/usr.bin/rcs/rcs.1

.\"	$OpenBSD: rcs.1,v 1.29 2006/04/19 13:50:38 jmc Exp $
.\"
.\" Copyright (c) 2005 Jean-Francois Brousseau <jfb@openbsd.org>
.\" Copyright (c) 2005 Xavier Santolaria <xsa@openbsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 16, 2004
.Dt RCS 1
.Os
.Sh NAME
.Nm rcs
.Nd RCS file management program
.Sh SYNOPSIS
.Nm
.Op Fl ehIiLMqTUV
.Op Fl A Ns Ar oldfile
.Op Fl a Ns Ar users
.Op Fl b Ns Op Ar rev
.Op Fl c Ns Ar string
.Op Fl e Ns Op Ar users
.Op Fl k Ns Ar mode
.Op Fl l Ns Op Ar rev
.Oo Fl m Ns Ar rev Ns :
.Ar msg Oc
.Op Fl o Ns Ar rev
.Oo Fl s Ns Ar state Ns
.Op : Ns Ar rev Oc
.Oo Fl t Ns Ar file Ns \*(Ba
.Ar str Oc
.Op Fl u Ns Op Ar rev
.Op Fl x Ns Ar suffixes
.Ar file ...
.Sh 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.
.Pp
The
.Nm
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
.Xr ci 1
and
.Xr co 1 ;
differences between revisions viewed or merged, using
.Xr rcsdiff 1
and
.Xr rcsmerge 1 ;
and information about RCS files and keyword strings displayed using
.Xr rlog 1
and
.Xr ident 1 .
See the respective manual pages for more information
about these utilities.
.Pp
.Nm
also supports
keyword substitution \(en
see
.Sx KEYWORD SUBSTITUTION ,
below, for more information.
.Pp
The following options are supported:
.Bl -tag -width "-e usersXX"
.It Fl A Ns Ar oldfile
Append the access list of
.Ar oldfile
to the access list of the RCS files.
.It Fl a Ns Ar users
Add the usernames specified in the comma-separated list
.Ar users
to the access list of the RCS files.
.It Fl b Ns Op Ar rev
Set the default branch to
.Ar rev .
.It Fl c Ns Ar string
Set comment leader to
.Ar string .
.It Fl e Ns Op Ar users
Remove the usernames specified in the comma-separated list
.Ar users
from the access list of the RCS files.
If
.Ar users
is not specified, all users are removed from the access list.
.It Fl h
Display the program's usage and exit.
.It Fl I
Interactive mode.
.It Fl i
Create and initialize a new RCS file.
If the RCS file has no path prefix, try to first create it in the
.Pa ./RCS
subdirectory or, if that fails, in the current directory.
Files created this way contain no revision.
.It Fl k Ns Ar mode
Specify the keyword substitution mode.
.It Fl L
Enable strict locking on the RCS files.
.It Fl l Ns Op Ar rev
Lock revision
.Ar rev
on the RCS files.
If
.Ar rev
is not given, the head revision is locked.
.It Fl M
Disable mail warnings when breaking a user's lock.
Normally,
.Nm
will send a mail to the lock owner when his lock is removed by a call
to
.Nm
.Fl u .
This option is currently ignored.
.It Fl m Ns Ar rev : Ns Ar msg
Replace revision
.Ar rev Ns 's
log message with
.Ar msg .
.It Fl o Ns Ar rev
Delete one or more revisions.
The specifications of the values or revisions are as follows:
.Bl -tag -width Ds
.It rev
Specific revision.
.It rev1:rev2
Delete all revisions of a branch between
.Ar rev1
and
.Ar rev2 .
.It rev1::rev2
Delete all revisions of a branch between
.Ar rev1
and
.Ar rev2
without deleting revisions
.Ar rev1
and
.Ar rev2 .
.It :rev
Delete all revisions of the branch until revision
.Ar rev .
.It rev:
Delete all revisions of the branch from revision
.Ar rev
until the last revision of the branch.
.El
.It Fl q
Be quiet about reporting.
.Sm off
.It Fl s Ar state Op : Ar rev
.Sm on
Sets the state of revision
.Ar rev
to the identifier
.Ar state .
The specified value may not contain a space character.
If
.Ar rev
is not specified, the latest revision of the default branch
is assumed.
.It Fl T
Preserve the modification time of RCS files.
.Sm off
.It Fl t Ar file \*(Ba Ar str
.Sm on
Change the descriptive text.
The descriptive text is taken from the
.Ar file
specified as argument or from the string
.Ar str
given as argument if it is preceded by the
.Sq -
character.
If no argument is used, the descriptive text is taken from standard input
terminated by end-of-file or by a line containing the
.Sq \&.
character by itself.
.It Fl U
Disable strict locking on the RCS files.
.It Fl u Ns Op Ar rev
Unlock revision
.Ar rev
on the RCS files.
If
.Ar rev
is not given, the head revision is unlocked.
.It Fl V
Print the program's version string and exit.
.It Fl x Ns Ar suffixes
Specifies the suffixes for RCS files.
Suffixes should be separated by the
.Sq /
character.
.El
.Sh KEYWORD SUBSTITUTION
As long as you edit source files inside a working directory you
can always find out the state of your files via the
.Xr cvs 1
.Ic status
or
.Ic log
commands, but as soon as files get exported from
your local working copy, it becomes harder to identify which
revisions they are.
.Pp
.Nm
and
.Xr cvs 1
can use a mechanism known as
.Sq 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 you
obtain a new revision of the file.
The possible keywords are as follows:
.Bl -tag -width Ds
.It $\&Author$
The name of the user who checked in the revision.
.It $\&Date$
The date and hour (UTC) the revision was checked in.
.It $\&Header$
Standard header containing the full pathname of the RCS
file, the revision number, the date (UTC), the author and the state.
.It $\&Id$
The same content as $\&Header$ but without the path
of the RCS file.
.It $\&Log$
The log message supplied during commit, preceded by a header
containing the RCS filename, the revision number, the
author, and the date (UTC).
.It $\&Name$
The tag name used to check out the file.
.It $\&RCSfile$
The name of the RCS file, but without a path.
.It $\&Revision$
The revision number assigned to the revision.
.It $\&Source$
The full pathname of the RCS file.
.It $\&State$
The state assigned to the revision.
.El
.Pp
Keyword substitution has its disadvantages: sometimes the
literal text string $\&Author$ is wanted inside a file without
.Nm
or
.Xr cvs 1
interpreting it as a keyword and expanding it into something like
$\&Author$.
The
.Fl k Ns Ar o
option can be used to turn off keyword substitution entirely though.
There is unfortunately no way to selectively turn off keyword substitution.
.Pp
Each file and working directory copy of a file have a stored
default substitution mode.
Substitution modes on files are set by the
.Fl k Ns Ar mode
option.
.Pp
The possible substitution modes are as follows:
.Bl -tag -width Ds -offset 3n
.It Fl k Ns Ar b
Like
.Fl k Ns Ar o ,
but also avoids the conversion of line endings.
This option is used to handle binary files.
.It Fl k Ns Ar k
Does not substitute the keywords.
Useful with the
.Xr cvs 1
.Ic diff
and
.Xr rcsdiff 1
commands to avoid displaying the differences between keyword substitutions.
.It Fl k Ns Ar kv
The default behaviour.
Keywords are normally substituted i.e. $\&Revision$ becomes
$\&Revision: 1.1 $.
.It Fl k Ns Ar kvl
Like
.Fl k Ns Ar kv ,
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
.Nm
and
.Xr cvs 1
do not use file locking by default.
.It Fl k Ns Ar o
No substitutions are done.
This option is often used with the
.Xr cvs 1
.Ic import
command to guarantee that files that already contain external keywords
do not get modified.
.It Fl k Ns Ar v
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
.Xr cvs 1
.Ic export
command to freeze the values before releasing software.
.El
.Sh ENVIRONMENT
.Bl -tag -width RCSINIT
.It Ev RCSINIT
If set, this variable should contain a list of space-delimited options that
are prepended to the argument list.
.El
.Sh EXAMPLES
One of the most common uses of
.Nm
is to track changes to a document containing source code.
.Pp
As an example,
we'll look at a user wishing to track source changes to a file
.Ar foo.c .
.Pp
If the
.Ar RCS
directory does not exist yet, create it as follows and invoke the
check-in command:
.Bd -literal -offset indent
$ mkdir RCS
$ ci foo.c
.Ed
.Pp
This command creates an RCS file
.Ar foo.c,v
in the
.Ar RCS
directory, stores
.Ar foo.c
into it as revision 1.1, and deletes
.Ar foo.c .
.Xr ci 1
will prompt for a description of the file to be entered.
Whenever a newly created (or updated) file is checked-in,
.Xr 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.
.Pp
The
.Xr co 1
command can now be used to obtain a copy of the checked-in
.Ar foo.c,v
file:
.Pp
.Dl $ co foo.c
.Pp
This command checks the file out in shared or 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
.Fl l
option of the
.Xr co 1
command.
Only one concurrent locked checkout of a revision is permitted.
.Pp
Once changes have been made to the
.Pa foo.c
file, and before checking the file in, the
.Xr rcsdiff 1
command can be used to view changes between the working file
and the most recently checked-in revision:
.Pp
.Dl $ rcsdiff -u foo.c
.Pp
The
.Fl u
option produces a unified diff.
See
.Xr diff 1
for more information.
.Sh SEE ALSO
.Xr ci 1 ,
.Xr co 1 ,
.Xr ident 1 ,
.Xr rcsclean 1 ,
.Xr rcsdiff 1 ,
.Xr rcsmerge 1 ,
.Xr rlog 1
.Sh STANDARDS
The flag
.Op Fl z
has no effect and is provided
for compatibility only.
.Sh CAVEATS
For historical reasons,
the RCS tools do not permit whitespace between options and their arguments.