To understand this document

This document assumes you standard UNIX™ shell, sh(1), have an understanding of the UNIX process model, exit codes, have coded several scripts, used gzip(1), find(1)

It also assumes that you can read the manual page for any other example command.

What is rcsvg?

rcsvg is an add-on to the standard RCS tools. It selects a named revision to co (check out) from all the cached files in a directory. The resulting shadow copy represents a point-in-time snap-shot of the cache, which may be used to create a stable build of the product the directory represents.

Since a common numeric revision is unlikely to be available, the named revision is usually a symbolic name, or the head revision, which co represents as a dollar sign ($). The numeric case is allowed, of course, as is selection by date (under -d).

Basic examples

To recover the current sources to rcsvg itself: 
$ cd /usr/msrc/local/bin/rcsvg
$ rcsvg -S /tmp/rcsvg.$USER '$'
$ ls -al /tmp/rcsvg.ksb/
total 76
drwxr-xr-x    2 ksb   wheel    220 Sep 10 11:43 ./
drwxrwxrwt  796 root  wheel  19880 Sep 10 11:43 ../
-rw-r--r--    1 ksb   wheel   2301 Sep 10 11:43 ITO.spec
-rw-r--r--    1 ksb   wheel    374 Sep 10 11:43 Makefile
-rw-r--r--    1 ksb   wheel   1926 Sep 10 11:43 Makefile.host
-rw-r--r--    1 ksb   wheel   1163 Sep 10 11:43 README
-rw-r--r--    1 ksb   wheel    352 Sep 10 11:43 TODO
-rw-r--r--    1 ksb   wheel   1302 Sep 10 11:43 machine.h
...
-rw-r--r--    1 ksb   wheel    169 Sep 10 11:43 util.h

The cd command above is typical, rather than providing a source positional parameter. This is in keeping with the idea that all RCS commands use the current working directory as an implicit parameter. The source parameter is used mostly by automation, not from the command-line.

Why do we need this?

Engineers and other workers may be working on the source to any configured item at any time. We always need to build production work-products from the stable sources, not some partially committed work-in-progress. Thus we use stable symbolic labels to fetch a known-good set of revisions.

Called by automation

Rcsvg is called by many of my tools to make stable copies of the files that compose both layer 2 and layer 3 sources:
level2s - manage layer 2 products

The level2s product manager (see the manual page, or the HTML page) uses this to cache a copy of each master source directory for the build sub-command.

level3s - manage layer 3 packages

The level3s package manager (see the manual page, or the HTML page) uses this to cache a copy of each master source directory for the build sub-command.

Package recipes fetch level2 products with rcsvg
Each package recipe file has a make rule to fetch every individual layer 2 product it includes: 
${STAGE}/local/bin/mkcmd: ${STAGE}/local/bin
	cd ${MSRC}/local/bin/mkcmd && rcsvg ${VGOPTS} -S $@ Eight

This is where the the symbolic name for each product is associated with the master source directory which supplies it. Note that the symbolic name in the package recipe should be distinct from the working label used by developers or testers. This is how we provide a stable copy, rather than the current test branch.

Site policy - presentation of layer 5 information
All of my layer 5 (site policy files) are kept under RCS. To create stable presentations the management make recipes use rcsvg and HTML conversion programs. Therefore the resulting web presentation always agrees with the data used by automation.

There is no magic here: if you use git as your layer 1 revision structure, then you would for a request to pull a clean copy from your authoritative repository. That is just another local site policy you'll have to work through. Site policy for revision control is your own business: I provide a simple model using RCS because it is common and relatively clear.

See also

The top-level master source document. 
$Id: rcsvg.html,v 1.3 2012/11/09 20:55:28 ksb Exp $