Getting started with CVS

As stated previously, CVS is now considered old and obsolete. If you have the choice, Subversion, Git, or Mercurial are all better options compared to CVS. But if you must learn it (or are just curious), read on.

(Most of this information it taken from the 1.11.23 manual, give it a second to load.)

First off: A little starter information

What is CVS?

CVS is a version control system, meaning that you can use it to record the history and changes to your files. For example, bugs can be introduced into a codebase and not be noticed until further down the line. CVS will let you roll back and look at every edit of the file, to see where exactly the bug was introduced, who caused it, and exactly what changes were responsible.

Now, you may ask what is the point of using another piece of software, when you can just save and back up a copy of the files at each change? Well.. you can, but that is far from optimal. For one, Most of these copies will never be used or needed again, and would consume huge amounts of unneeded disk space. CVS stores changes in a single file that only stored the differences (or deltas) between different versions, saving space.

CVS also allows multiple people to work on the same project, or even the same files, at the same time without overwriting each other's changes. (Given the name of Concurrent Versions System, this part should be obvious)

What is CVS not?

CVS can't do everything.

• CVS is not a build system, it merely stores files for your retrevial.
• CVS does not dictate how you lay out your code.
• Determining when files need to be rebuilt is not covered by CVS.
• CVS is not a substitute for management. Nor is it a substitute for developer communication. Everyone needs to be on the same page to make sure that release dates, file versions, branch names, and tag names are all consistent and meaningful.
• CVS is not an automated testing system, nor a bug tracker.

A sample session

To introduce you to CVS, we will walk you through a typical work session of CVS. The first thing to understand is how CVS stores files, in a central location named the repository, more on this later.

Note, we are skipping over module naming and telling CVS where the repository is, that will be covered later. For now you need not worry about it.

Now, suppose you are working on a simple compiler. The source consists of a handful of C files and a Makefile. The compiler is called tc (Trivial Compiler), and the repository is set up so that there is a module called tc.

Getting and editing the source

The first thing you must do is create a working copy, that is, download a copy of all files from the repository in their current state to the machine that you plan to do your work on. this is done with the checkout command, like so:

$ cvs checkout tc

This will create a directory named tc and fill it with the current versions of all the files in the project.

$ cd tc
$ ls
CVS/    Makefile        backend.c       driver.c        frontend.c      parser.c

The CVS directory is used internally and required by CVS. You do not need to worry about it, but do not go in and edit the contents.

At this point, you start your favorite editor and add an optimization pass to the compiler.

Committing your changes

WHen you have tested your modifications and determined that they didn't break anything, you decide to add a new version of backend.c so that everyone else on the project can use your edit. This process is called a check-in, or preferrably, a commit, and is done like so:

$ cvs commit backend.c

CVS will start an editor, allowing you to input a brief message so that everyone else knows at a glance what you changed. You enter "Add an optimization pass", save the file, and close the editor.

The environent variable $CVSEDITOR is used to determine what editor to open, be it vi, vim, nano, emacs, or some other editor. If $CVSEDITOR is not set, $EDITOR will be used instead. If both are not set, the default for your operating system will be used.

If you wish to avoid starting the editor, the commit message can be passed on the command line, like so:

$ cvs commit -m "Add an optimization pass" backend.c

Cleaning up

Before you work on another project, you decide to clean up your working copy of the tc project. The quickest and most obvious way is to simply delete it:

$ cd ..
$ rm -r tc

A better way is to use the release command (which will be covered in more detail later):

$ cd ..
$ cvs release -d tc
M driver.c
? tc
You have [1] altered files in this repository.
Are you sure you want to release (and delete) directory `tc`: n
** `release` aborted by user choice.

The release command will warn you if you have edits that you've yet to commit. When used with the -d flag, the release command will delete the directory (and therefore, your working copy).

In the example above, release gave a few lines of output to warn you about the state of your working copy. ? tc means that the file tc is unknown to CVS. tc in this case is the executable produced by the compiler, and therefore is nothing to worry about. That file does not belong under CVS control anyways. There are ways to get CVS to ignore these files but that will be covered later.

The line M driver.c is a bit more serious. This means that CVS has detected that you changed driver.c but haven't yet commit those changes to the repository. If you release your working copy now, these changes will be lost permanently.

Afterwards, release always informs you of how many fies you have made changes to, and asks if you're sure if you want to do this. You decide to play it safe and answer n to the prompt.

Viewing differences

You don't remember changing driver.c, so you ask CVS to tell you the changes it sees in the file:

$ cd tc
$ cvs diff driver.c

The diff command runs a diff (file comparison) program (diff by default), to compare the version that you last checked in against the version in your working copy. WHen you see the output of this you remember that you added a command line option to enable optimization, and it should be added too. You check this in, and then release your working copy.

$ cvs commit -m "Add optimization pass" driver.c
Checking in driver.c;
/usr/local/cvsroot/tc/driver.c,v  <--  driver.c
new revision: 1.2; previous revision: 1.1
done
$ cd ..
$ cvs release -d tc
? tc
You have [0] altered files in this repository.
Are you sure you want to release (and delete) drectory `tc`: y

The repository

The CVS repository stores a complete copy of all files which are under version control.

Normally, you never access any of these files directly. Instead, you use CVS commands create a copy of the files, called your working directory, you work on that copy, and commit the modified files back into the repository. (Note, the process of checking in files is called a commit.) On TD-StorageBay, the repository lives on the StorageBay servers, and your working copy (or copies) live on your computer(s) that you plan to edit files with.

CVS is capable of accessing a repository through a variety of means, though the one used on TD-StorageBay is known as the :pserver: (Also known as pserver, p-server, cvspserver, and the full name of CVS Password Server.) When telling CVS where your repository is, you prefix the location with an access method. For example, to access a repository on your local computer at /usr/local/cvsroot, you would tell CVS that your repository is at :local:/usr/local/cvsroot (though if the location starts with a /, :local: is assumed). Repositories on TD-StorageBay are stored in /srv/cvs/, with a directory for each user, and further more for each project. So a StorageBay repository would be accessed like so: :pserver:user@gen.tdstoragebay.com:/srv/cvs.

Telling CVS where the repository is

There are two main ways to tell CVS where to find the repository that you wish to work on. The first is to pass the information on the command line with the -d option:

$ cvs -d :persver:jack@gen.tdstoragebay.com:/srv/cvs checkout jack/foo

Or alternatively, you can set the $CVSROOT environment variable. If you wish, is can be set automatically using the .profile or .bashrc files (csh and tcsh are not covered here):

CVSROOT=:pserver:jack@gen.tdstoragebay.com:/srv/cvs
export CVSROOT

Using the -d option will override $CVSROOT.

Once you have checked out a working copy, that copy will remember where the repository it was copied from resides, meaning you only have to explicitly specify it once.

For most purposes, how CVS stores data in the repository isn't important. If you've been named a server admin, it may be of use to you. This can be found in the guide to CVS administration.

Logging in

When using and CVS server running cvspserver, you will need to log in before you can access files (unless the repository has accounts with no passwords). The easiest was is to use the CVS login command. Unless you're specifying a repository with -d, the syntax is simple:

$ cvs login
CVS password:

You can also specify a password to -d, like so:

$ cvs -d :pserver:jack:s3cur3_p455w0rd@gen.tdstoragebay.com:/srv/cvs login

After the password is entered, CVS verifies it with the server. If the password is correct, that combination of username, server, and repository is stored so that it can be used again without user intervention (unless the password on the server changes, then future requests will fail with the incorrect password). If you wish to remove your passwords, cvs logout will delete the records, meaning you'll have to cvs login next time. Those records that CVS stores are in the file ~/.cvspass and stored with minimal encoding. If you want to use a different file, the environment variabe $CVS_PASSFILE is read at the start of cvs login, and therefore you will need to change it before running cvs login.