.\" @(#)  /u/des/src/rc/rc.man  1.3  99/09/09  22:54:16
.\" Copyright (c) 1999, Daniel E. Singer
.\" All Rights Reserved
.\" view this document using [tn]roff with the -man option
.TH rc 1 "14 June 1999" "Toolman"
.\" ------------------------------------------------------------------------
.\" define string D to be a dash appropriate for nroff or troff
.if n .ds D -
.if t .ds D \-
.SH NAME
rc \*D automate the revision control edit cycle
.SH SYNOPSIS
.BR rc " [ " \*Dhpqx " ] [ "
.BR \*Di "|" o " ] [ "
.BR \*Dr "|" s " ] [ " \*Dc
.IR comment " ] "
.RI "[" path/ "]" file
.br
.\" ------------------------------------------------------------------------
.SH DESCRIPTION
.B rc
(revision control)
automates the check-out/edit/check-in cycle of files maintained under the
.B RCS
and
.B SCCS
revision control systems.
.B rc
performs various checks to determine which type of revision control to use;
does initial entry of
.I file
to revision control;
warns you if you're
.BR root ;
creates a new file when appropriate;
restores execute bits on
.B SCCS
files;
changes directory to a specified
.IR path ;
and more.
.\" ------------------------------------------------------------------------
.SH OPTIONS
The following options are supported:
.\" ---
.TP 10
.B \*Dh
Help, just print an informational message, and exit.
.\" ---
.TP
.B \*Dp
Do not preserve file permissions, default is to preserve
any read and execute permissions
.BR " " "(" SCCS
only).
.\" ---
.TP
.B \*Dq
Quiet, minimal prompts and messages.
.\" ---
.TP
.B \*Dx
Set execute bits when creating a new file.
.\" ---
.TP
.B \*Di
Just do a check-in of the file, and exit.
.\" ---
.TP
.B \*Do
Just do a check-out of the file, and exit.
.\" ---
.TP
.B \*Dr
Favor
.BR RCS .
.\" ---
.TP
.B \*Ds
Favor
.BR SCCS .
.\" ---
.TP
.B \*Dc
Supply a comment for the revision.
.\" ------------------------------------------------------------------------
.SH OPERANDS
The following operands are supported:
.TP 10
.I path
An optional directory path to
.BI file .
.TP 10
.I file
The file to be acted upon.
.\" ------------------------------------------------------------------------
.SH USAGE
.\"
.SS Selection of Revision Control Type
Selection of which of
.B RCS
or
.B SCCS
to use in a given situation is handled in one of these ways:
First, if the file already exists and is under revision control, this will be
detected and the appropriate type will be selected; other options will only come
into play in the unlikely situation that the same file appears to be under
both types of revision control.
Second, if one of the
.B \*Dr
or
.B \*Ds
command line options is specified, then that type will be selected.
Third, if the
.B RC_FAVOR
environment variable is set to one of \*(lqRCS\*(rq or \*(lqSCCS,\*(rq
then that type will be selected.
Finally, in the absence of the other selection methods, the setting of
the variable
.B DFLT_FAVOR
in the
.B rc
script itself will determine the selection.
The last three selection methods come into play primarily for files that are
first being put under revision control or are just being created.
.\"
.SS Preservation of Mode Bits
.B SCCS
has the annoying habit of dropping any execute bits (and other special mode
bits) that are set on a file during check-out or check-in.
By default,
.B rc
will preserve these mode bits, after both check-out and check-in.
This behavior can be suppressed with the
.B \*Dp
option.
.\"
.SS Root Detection
.B rc
will warn you if it detects that your effective user ID is
.BR root ,
and will give you the opportunity to bail out.
Typically, it is considered bad form to revise as
.BR root ,
since then no meaningful record is kept of who did the revising.
.\"
.SS Files Already Checked Out
When starting up,
.B rc
will inform you if any files in the working directory are checked out,
and by whom.
If the file you've specified is checked out, you have the option of
bailing out or continuing to the edit step.
.\"
.SS Initial Check-In
If the file is not already under revision control,
.B rc
will allow you to create a history file (ie, check the file in)
before editing begins.
Even if you don't create the history file, you can still edit.
.\"
.SS File Creation
If the file does not exist,
.B rc
will still allow you to go on to the edit step,
and will then let you optionally do an initial check-in.
.\"
.SS Not Checking Back In
After the edit step, you are asked if you want to check the file back in.
If you choose not to, you will also be asked if you want to \*(lqunedit\*(rq
the file.  If you do choose to unedit the file, it will be restored to
the revision it was at when you started.
.\"
.SS Using as a Wrapper
With creative use of the editor environment variables (see below),
.B rc
can be used as a wrapper to run any program that needs to modify a
file that is otherwise under revision control.
.\"
.SS Embedding
.BR \*Do ,
.BR \*Di ,
and
.B \*Dc
can be used to tailor
.BR rc 's
actions so that it can be used inside of other programs where
a file must at some point be checked out, modified, and later checked
back in.
Several of the environment variables (see below) can also be used
to more subtly tune the default behaviors of
.B rc
in these situations.
.\"
.SS The Editor
By default,
.B rc
will use 
.BR vi (1)
as the editor, but this can be overridden via any of various
environment variables (see below).
.\" ==============================================================================
.\" ------------------------------------------------------------------------
.SH ENVIRONMENT VARIABLES
.TP 14
.B RC_FAVOR
The type of revision control to favor.  Set to either of
\*(lqRCS\*(rq or \*(lqSCCS.\*(rq
.TP
.B RC_EDITOR
The editor (or other program) to use during the \*(lqedit\*(rq
part of the cycle.
.TP
.B RC_QUIET_CREATE_HIST
If set to a non-null value, the
.B \*Dq
option is selected, and
.I file
is not under revision control, then
.I file
is put under revision control.
.TP
.B RC_QUIET_CREATE
If set to a non-null value, the
.B \*Dq
option is selected, and
.I file
does not exist, then
.I file
is created.
.TP
.B VISUAL
If \fBRC_EDITOR\fR is not set, this will then be used to specify the editor.
This usually specifies a full screen editor.
.TP
.B EDITOR
If \fBRC_EDITOR\fR and \fBVISUAL\fR are not set,
this will then be used to specify the editor.
.\" ------------------------------------------------------------------------
.SH DIAGNOSTICS
Returns \fB0\fR if no problems encountered.
.br
Returns \fBnon-zero\fR if any errors encountered.
.\" ------------------------------------------------------------------------
.SH BUGS
Cannot handle multiple file arguments.
.\" ------------------------------------------------------------------------
.SH "SEE ALSO"
.BR chmod (1),
.BR rcs (1),
.BR sccs (1),
.BR vi (1);
.br
\*(lqToolman:  Revision Control Revisited,\*(rq
\fI;login:\fR magazine (USENIX Association), October 1999.
.\" ------------------------------------------------------------------------
.SH AUTHOR
.B rc
was written by Daniel E. Singer (a.k.a. Toolman)
at the Department of Computer Science, Duke University.