CVS Tips 'n Tricks

What is CVS?

CVS is short for Concurrent Versions System. CVS is a tool that
enables one or more developers, possibly spread over the entire
planet, to work on common projects (applications, web pages,...).

The heart of CVS is the so-called repository, a kind of
database residing on a server, which stores all versions of all files
in that repository as well as log entries that specify the three Ws:
Who? When? What resp. why?

A repository is shared by all contributors, and contains one to
many modules, which usually are self-contained parts of a common
project, like web pages, documentation, and test suites, for example.

Each contributor usually has one (or more) local copies of those
modules she is working on. There she performs changes and does the actual
development. Once a contributor is satisfied with her changes, she
commits these to the repository.

In general, it is never necessary to access the repository (resp. the
machine carrying the repository in the case of remote CVS) directly. All
interaction between the user and the repository is performed by means of
the cvs command on the local machine.

CVS Kickstart

In the following, we will provide a short overview on how to use CVS
with an already existing repository. Information on how to create a
repository can be found in the CVS manual
(see References).
(A significant part of this section has originally been contributed
by Lothar Mauerhofer.)

The Repository

To let CVS know which repository it should use, you have to set a
special environment variable, like

setenv CVSROOT /home/pfeifer/DLV/CVS for DLV

It is recommended to insert this line into your startup files,
e.g. ~/.cshrc, though you won't really need it once you
have checked out a local copy.

Creating a Local Copy

Every CVS repository contains one to many modules, which usually
are self-contained parts of some larger system.

DLV currently has the modules dlv (the
system itself), and dlvtests (the testsuite);
and VIBE.AT currently has the module www.

Use the CVS checkout command to create a local copy of
the entire CVS module you are interested in.

cvs checkout $MODULE

To properly remove a local working copy:

cvs release -d $DIRECTORY

By default, $DIRECTORY is the same as $MODULE, but you can rename a
checked out directory without any problems. However, do not
remove any subdirectory called CVS as this will destroy vital
information for the CVS system.

Keeping Track of Changes

To view changes made to your local copy:

cvs diff
cvs diff filename(s)

To view the change log of the source files:

cvs log
cvs log filename(s)

Incorporating Changes in the Repository

To merge changes that have been made to the repository (by other
contributors, for example) since you checked out your copy or did the last
cvs update into your local copy:

cvs update

Committing Your Changes to the Repository

Basically there are two ways to get your changes into the
repository: Submitting patches to a/the maintainer, and committing
directly. In any case, please do not forget to issue a cvs
update directly before preparing the patches resp. committing.

Submitting patches

Create a patch file for the concerned files:

cvs diff -c3p filename(s) > mypatch

Send an appropriate description (and possibly an entry for the log
file) by email with the previously created patch file attached.

(Instead of -c3p you can also use -u3p.
Both options will add a bit of context, that is, three lines before
and after each difference will be included as part of the patch.)

Direct Commit

In case that you have the authorization, you can commit changes in
your local working copy directly to the repository:

cvs commit
cvs commit filename(s)

This will invoke the default editor of your system which usually can be set
by means of the EDITOR environment variable, e.g. setenv EDITOR
xemacs when using tcsh or EDITOR=xemacs when using sh.

General Guidelines and Caveats

Check in minimal, though self-contained patches. Each commit (and thus
each log entry) should provide exactly one fix resp. enhancement.

Hints and conventions for log entries:

Do not make log entries wider than some 73 characters.

Do not use blank lines in log entries.

Logs should consist of complete sentences, with a "." at the end.

C/C++: When referring to function names, add () directly
after the name, omitting the explizit description ``function'' or similiar.
Refer to operators as in operator() or
operator+(T,float).

When you take some file home and modify it there, do
notcvs update before copying back that
file, or your next commit will undo all changes that have been made
to the repository in the meantime.

Using CVS remotely

If the site keeping the repository has a ssh server installed, you
can easily access the repository remotely by setting

CVS_RSH to sshCVSROOT to :ext:$USER@$HOST:$PATH

where $USER is your
remote username, $HOST the remote host and
$PATH the directory of the repository.

CVS, SSH, and Windows

Obviously, Windows, the emporer of proprietary systems, causes all sorts
of problems when dealing with open protocols and standards like CVS and SSH,
but still it is possible use this combination also there, for example using
Cygwin.