CVS Tips 'n Tricks

What is CVS?
CVS Kickstart
General Guidelines and Caveats
Using CVS remotely
CVS, SSH, and Windows
Further Sources of Information

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 not cvs 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 ssh
CVSROOT 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.

References