Alpha_1 Programmers's Manual

Using CVS with Alpha_1 under Emacs

VC: Version Control under Emacs

CVS is supported under Emacs 19 and above through a package called "VC", which suppors several version-control systems: SCCS, RCS, and CVS. CVS actually does version control to entire source trees, using RCS on individual source files. Emacs "info" contains on-line documentation for CVS and its shell (command-line) invocation and options, invoked through C-h i or menubar "Help/Info (Browse Manuals)".

VC integrates normal CVS usage into Emacs. You can tell when a file is known to CVS by looking at the mode line in Emacs. It will have the annotation "CVS", followed by the current version number.

GDC group specific Emacs commands

/res/gdc/projects/general/emacs/gdc_general.el binds the following two commands as a top-level interface to VC and CVS:

The C-c w command (to-working-subdir) is GDC specific, implemented in /res/gdc/projects/general/emacs/gdc-cvs.el . Invoke this command before changing a source file read in from Alpha_1, URT, or another software project of the GDC group which is managed by CVS.

When invoked on a file under $a (the source tree), to-working-subdir creates the working directory if necessary, does does a "cvs update" to put the current repository version of the file onto your workdir, and changes the buffer-filename of the buffer to point under your workdir. It can also be invoked on files which were read in from $w (your working directory tree), and makes sure your working directory copy of the file is up-to-date.

% f is a subcommand of Dired mode, used by VC on a directory. This is described under Working directory cleanup below.
The C-c u command (vc-directory) is equivalent to C-x v d, the entry to dired-under-vc-mode. This is a submode of the Emacs "Dired" (directory editor) mode, which is what C-x C-f (find-file) does on a directory. You are prompted for a directory path, and get a buffer containing a listing of files known to CVS in the directory, one per line. Dired is very powerful, as shown by the many special menu entries which show up on the menubar when you are in a Dired buffer (Operate, Mark, Regexp, Immediate, and Subdir commands.)
Keystrokes bound to VC commands (described below) will execute as though they had been called on a buffer attached to the file named in the current Dired buffer line. Many regular Dired commands work as well, for example the g command refreshes the directory listing.
Files are marked as (modified) if they have been changed from the repository version, (added) if they have been registered with CVS and need to be checked in to commit the addition, or (patch) if somebody has checked in a change and the copy on your directory is out of date.
Many of the commands work on a whole marked set of files at once. For example, you only have to enter the change reason once if you mark a bunch of files with m and commit them together at one time with C-x v v.
The C-u prefix modifier, C-u C-c u tells it to show all files known to CVS which are present on the subdir, not just those which have been changed.

VC Emacs commands

The VC command keystrokes start with the prefix C-x v. The VC commands are also available under the menubar from a Tools/Version Control submenu.

These are purely informational VC commands:

C-x v = (vc-diff) - This does a "cvs diff" and shows the result in an Emacs buffer named *vc-diff*.
C-x v l (vc-print-log) - Shows the ouput of "cvs log" on the current file in an Emacs buffer named *vc*.

You should always look at the diffs before checking in a change.

These are the most useful VC commands:

C-x v i (vc-register) - This does a "cvs add". (Note that this must be done on the source file itself. It can't work in vc-directory mode, since unregistered files don't show up in that window.)
C-x v v (vc-next-action) - This is the "master command", which does the next logical operation on the current file. It registers new files, updates patched files, and commits changes to modified or added files.
When you start to commit a change, a buffer named *VC-Log* appears for your change comment. M-p goes backward in the change comment history to re-use comments, and M-n goes forward. C-c C-c finishes the checkin.

These are the rest of the useful VC commands:

C-x v u (vc-revert-buffer) - Does a "cvs update" on the file and updates the copy in Emacs (if any).
C-x v d (vc-directory) - Visits a directory under VC. Same as the traditional Alpha_1 binding, C-c u.
C-x v ~ (vc-version-other-window) - Check out a particular version of the file. Do this on working directory files, rather than source tree files, because the result is put into a file in the current directory. The file name includes the version number and so doesn't conflict with the current source file.
C-x v c (vc-cancel-version) - Get rid of most recently checked-in version of this file.
C-x v g (vc-annotate) - Display the result of the "cvs annotate" command using colors. New lines are displayed in red, old in blue. (We haven't used CVS annotations yet in Alpha_1.)

These appear to be RCS specific, rather than CVS. I've never used them.

C-x v s (vc-create-snapshot)
C-x v r (vc-retrieve-snapshot)
C-x v h (vc-insert-headers)
C-x v a (vc-update-change-log)

Working directory cleanup

To clean out your workdir when you're done checking in, you can use Dired to delete the working files (leaving the CVS subdirectories!)

Specifically,

Do C-x C-f <Return> in the CVS window that resulted from C-c u above.
Mark your checked-in files for deletion using the d key. (This is a good time to clean up .o files and Dependency.make files as well.)
Optionally use the ~ (tilde) key to mark all backup files for deletion.
Execute the deletions with the x key, and answer "yes" when it asks if you really want to do that.
Finally, execute Tim's fix-cvs-entries shell script on the directory using the % f key combination, which is bound to the dired-fix-cvs-entries function in gdc_general.el .

If you don't do this last step, the source files you cleaned up will all be re-created by the next "cvs update" command, and it will whine that they are missing as well.