.\" $Id: rcsvg.man,v 2.18 2012/02/29 18:45:20 ksb Exp $
.\" by Kevin Braunsdorf
.\" $HTML: ${groff-groff} -tbl -man -Thtml %f
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -tbl -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -tbl -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/rcsvg.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/rcsvg.1*
.TH RCSVG 1 LOCAL
.SH NAME
rcsvg - RCS version grab, form a stable copy of an RCS cached product
.SH SYNOPSIS
.ds PN "rcsvg
\fI\*(PN\fP [\fB\-cdfmnRv\fP] [\fB\-S\fP\~\fIstage\fP] \fIversion\fP [\fIsource\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
\fBRcsvg\fP extracts a consistant set of revisions from the RCS
cache for a product.  These revisions (which all have a common
symbolic number) are refered to as a stable version of the product.
.PP
The positional parameter \fIversion\fP is the symbolic number
of the version of the product requested.  \fIRcsvg\fP \fBco\fP's
from each RCS cache in the \fIsource\fP direcrtory (default ``.'')
the revision \fIversion\fP dumping the output to a parallel
direcrtory structure under \fIstage\fP (default \fB/tmp/\fP\fIversion\fP).
.PP
The checked-out source in the heirarch is left undisturbed.  Any
symbolic links in the source are copied as-is.  \fIRcsvg\fP
descends any subdirectories (except \fBRCS\fP) after finishing
the current level.
.PP
Some error conditions are flagged with bits in \fI\*(PN\fP's exit
status, some exit code from \fBsysexits.h\fP may also be returned:
.RS
.TS
c l.
1	RCS cache file not readable
2	found a character or block special file
4	symbolic link through / or off top
8	found a trash file in RCS
.TE
.RE
.SH OPTIONS
This command reads the environment variable \fBRCSVG\fP for options.
.TP
.BI \-c
Any files which \fBcmp\fP(1) the same as their already staged
revision are not updated.
This is limits the impact of \fBmake\fP(1) dependency updates.
.TP
.BI \-d
Use the \fIversion\fP parameter as a \fIdate\fP to \fBco\fP's \fB\-d\fP option,
rather than a parameter to \fBco\fP's \fB\-r\fP option.
.TP
.BI \-f
The \fB\-m\fP flag creates read-only files in the stage directory
which overlayed collections cannot write over: this flag forces
an unlink of all target files (that exist) before we try to
checkout on top of them.
.TP
.BI \-h
Print a short help message.
.TP
.BI \-m
Use the modes on the RCS cache files, rather than the checked out
revisions, for the staged files.
.TP
.BI \-n
Do not execute commands, trace only.
.TP
.B \-R
Create a symbolic link back the the RCS cache directory from which we built
the checked out files.  This is mostly useful for running rcsclean to
cleanup the stage when we are done playing.
.TP
.BI \-S stage
Specify a staging area we should construct/update the requested version.
The default \fIstage\fP is \fB/tmp/\fP\fIversion\fP.
.TP
.BI \-v
Output verbose shell-like commands the describe actions.
.TP
.BI \-V
Show version information.
.SH EXAMPLES
.TP
.nf
\fBrcsvg\fP \-S /tmp/ksb Second /usr/msrc/local/bin/rcsvg
.fi
Extract the version of this program named ``Second''.
.TP
.nf
\fBrcsvg\fP \-c Four
.fi
Extract the version ``Four'' of the program in the current
directory to /tmp/Four.  Do not change any files which are already
there and are the same.
.TP
.nf
\fBrcsvg\fP \-S /tmp/l2s \-d "16:00 lt" /usr/msrc/local/sbin/level2s
.fi
Fetch the version of \fBlevel2s\fP from before I started working
on it today at 16:00 (localtime).
.SH BUGS
The checking for symbolic links that leave the subtree is not
fully implemented (yet).
.SH AUTHOR
KS Braunsdorf
.br
rcsvg ~ not spammed ~ at ksb.npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), rcsintro(5), co(1), mkdir(1), cmp(1), make(1), level2s(8l), ln(1),
symlink(7), msync(8l)