Taglets Collection

This document gives a short introduction to the Concurrent Versions System (CVS) used to manage the source code.

Documentation

There is a lot of documentation available on how to use CVS. Recommended links include:

• The CVS Manual Page (shell command man cvs).
• The TeXinfo pages (shell command info cvs).
• The online CVS Manual
• German translation of the manual.
• And an excellent free book: The CVS Book.

Initial Configuration

~/.cvspass

When CVS is used to access a CVS server over the network it tries to send a password to the remote system. This password is usually taken from the ~/.cvspass file in the users home directory. If there is no such file the cvs command will print a warning message. To suppress that message run the following commands.

$ touch ~/.cvspass
$ chmod go-rwx ~/.cvspass

The above sequence creates an empty ~/.cvspass file that is readable only by the user to ensure that password that are written to this file later on cannot be read by someone else.

~/.cvsrc

Many cvs options are needed or wanted every time cvs is used. Therefore cvs reads in default options from the startup file ~/.cvsrc. The following ~/.cvsrc file may serve as an initial version:

$ cvs -z3 -q
$ update -Pd
$ checkout -P
$ diff -uw

Meaning:

cvs -z3 -q:

-z3: Always compress files that are transferred across the network use gzip(1) with compression level 3. This compression level gives a good compromise between usage of network and computing power.
-q causes cvs to be somewhat quiet.

update -Pd

-d: Whenever an update is made directories, that are new in the repository should checked out automatically.
-P: Prune (remove) directories (from your checked out copy) that are empty after being updated.

checkout -P

-P: Prune (remove) directories (from your checked out copy) that are empty after the checkout.

diff -uw

-w: While showing differences between different versions of the same file ignore all blanks (SPACE and TAB characters) and treat all other strings of blanks as equivalent. For example, 'if ( a == b )' will compare equal to 'if(a==b)' and no differences would be shown. This option makes it easier to see the "real" diffrences after cleaning up the source code.
-u: Show three lines of context around the changed code.

Common Usage Patterns

Update

Updating your copy of the repository with the most current version is probably the most important task. Updates are always done with the CVS sub command update. If one or more files are given as arguments only these files and directories will be updated, otherwise the current working directory is updated. Usually it is good practice to start the update recursively from the top level directory of the project. Given that the above ~/.cvsrc file is used the following command sequence will update your whole project.

$ cvs update

Due to the ~/.cvsrc file the last command expands to cvs -z3 -q update -Pd and the whole project directory will be updated at once. For each file that is newly created or updated in your copy or changed locally you will get one line of output starting with a single letter expressing the concrete status of the file (see table 1 for details) ant a file name.

Sometimes it happens that someone else has changed a file and checked it in that has been modified by you, too. CVS tries to merge these changes together. Most of the time these merges succeed. But if the same lines of code have been change by you and someone else the merge cannot be done automatically and CVS creates a so-called conflict file. The file is also marked by a 'C' in the output of cvs update.

The conflicts in the conflict files have to be resolved manually. This can be done either with an editor or with the use of some merge utility (e.g. tkdiff -conflict <conflict file>).

Checkin

Before you can successfully check in your changes three preconditions have to be met:

1. Your copy has to be up to date. Therefore the command cvs update has to be used (in the top level directory of the project).
2. If there are files marked by a question mark in the output of the update command, these file have to be treated:
   1. All new file (and directories) have to be added explicitly by the command cvs add <file>.
   2. All removed file have to be removed explicitly by the command cvs remove <file>.
   3. Eventually you also have to add some files to a .cvsignore file to tell CVS that these file should be ignored.
3. Your copy of the project directory should be "correct". I.e. it has to compile and all unit test should succeed.

Since updates may change the code (and the correctness of the code) the above two steps might be needed to be done more than once. Finally the output of cvs update shouldn't have any lines marked by an 'U' or '?'.

When you are done with the cycle of updating and building (build world) the project the checking can be done. Therefore change to the top level directory of the project and run cvs commit.