CVS is the version control system used by the SEUL project. RCS and SCCS are other common version control systems that you may be familiar with. These are all systems that allow a development team to keep a central repository of sources, which may then be checked out by various developers, modified, and checked back in to the main repository.

Version control systems also allow operations which help keep track of source modifications over time, such as listing differences between revisions of files, and tagging sets of files that constitute a complete software release. They also resolve issues (to some degree) that arise when multiple developers want to work on the same file simultaneously. RCS forces locking of files, so that only one person can work on a file at once. CVS, however, recognizes that with proper planning and communication there is no reason multiple people can't work on one file at once. So CVS allow any number of copies of the same file to be worked on at once, and implements methods for merging changes, as well as some support for watching who is editing what, to avoid surprise conflicts. However, it is important to keep in mind that CVS will not do everything for you, and most notably is not a replacement for communicating with other developers working on your project.

More information on CVS can be found in the official CVS documentation. This may be found in /usr/doc/cvs-*/cvs.ps on a system with cvs installed, in the ftp pub dir on cran (eventually), and a slightly outdated html version is on the web at http://hill.ucs.ualberta.ca/Documentation/cvs-1.8.1/cvs_toc.html. If you plan on working on the SEUL project extensively, you should probably read through that document eventually, or at least refer to it when you're not sure how some part of CVS works.

For now, a quick intro for getting started with CVS as related to SEUL may be found below. However, it is not meant to replace the full documentation, but merely to offer a quick-start for using CVS for SEUL development.

What?

Once you have CVS installed on your machine, you'll need to create a directory to place your working copies:

# mkdir work
# cd work

The next step is to specify your where your repository is. This is done either from the command line, ~/.cvsrc, or your environment. Putting it in the environment is usually the easiest, and is not a problem if you use mulitple repositories, as the command line argument will override it:

# setenv CVSROOT=/path/to/cvsroot

for csh and derivitives, or the following for Bourne shell and similar:

# export CVSROOT /path/to/cvsroot

Getting started

A local repository (i.e. one on the same machine your working copy is on) is specified simply by the directory that contains it. A remote repository is more complex, because much more information is necessary in order to get to the repository.

The most common method of getting to a remote repository is via rsh, which provides CVS with a bidrectional channel to operate on top of. SSH operates as a drop-in replacement for rsh and provides such features as strong authentication and encryption, and a compressed channel.

Setting the respository variable to use the rsh access method is relatively straightforward:

:ext:user@site.dom:/path/to/cvsroot

You can also use a built-in server method, if the remote repository supports it. Kerberos can be used to authenticate your connection, again if the remote side supports it.

The repository

In order to make modifications to any files in the repository, you must start from a working copy. Obtaining a working copy is done through a process called "checkout", during which the most recent copy of all the files in the repository are copied into your working directory.

As a matter of habit, all your working copies should be placed in one location, such as a work directory. Each repository you work on might have its own subdirectory within work.

To checkout a directory from the repository, you simply make sure you're looking at the right repository (set $CVSROOT or use the command line), and in the right directory. Then issue the following command:

# cvs checkout dir

This will give you a working copy of dir in the current directory.

Checkout

Once you've made your changes to the appropriate file(s), you have to commit them in order to make your changes occur in the repository. In this process, your local copy is compared with the copy you checked out, as well as the most recent version, and any changes are merged. If CVS can't merge the changes, you have to do it manually.

To commit files to the repository, execute the following command:

# cvs commit file1 file2

You will be given an editor to write a log message. This log message should explain all the changes you made to the file. It is the only way someone can tell later on what you did for that revision. They can view the changes easily enough, but that isn't always enough.

You can also specify the log message on the command line, such as:

# cvs commit -m "log message here" file

Committing

Adding new files and directories to the repository is a very simple process, really. All you do is create the file or directory, tell CVS that you want to add it, and commit it if you're adding a file:

# mkdir newdir
# cvs add 
# echo something > newfile
# cvs add newfile
# cvs commit -m "added a new file!" newfile

There is one pitfall that you have to be careful of, though: If you create a directory and populate it with files before you do a cvs add of the directory, it will fail when you do run it. Any directory added must be completely empty. If you're stuck, simply move the files into a temporary directory, add the directory, and move the files back.

Adding stuff