A Quick and Dirty Guide to CVS



Like RCS, CVS is a version control system. Unlike RCS, it allows multiple developers to work on a file at the same time; the C in CVS stands for "concurrent".

This document is a simple introduction from a user's point of view. It assume that a repository already exists. That is to say, someone has already run cvs init, to initialize the repository, and cvs import to add the first group of files.

As a general reference, the main CVS manual is available online at http://ximbiot.com/cvs/manual/feature.

Setting up Your Environment

Before using CVS, you'll need to set up a environment variables.

setenv CVSROOT /path/to/cvsroot          # C-shell syntax
CVSROOT=/path/to/cvsroot; export CVSROOT # Bourne syntax

CVSROOT should be the directory path to the repository. Place these in your .cshrc, .profile, or where ever you normally put such things.

Another useful variable is CVSEDITOR. When ever you commit files, cvs will invoke this program and allow you to provide comments about the change you are making. As a personal preference, I like "emacs -nw --no-init-file"

General Syntax of CVS commands

CVS commands take the following form

cvs cvs-options subcommand subcommand-options

subcommand is the thing you are asking cvs to do -- check files in, check files out, do diffs, etc. To see the syntax of a given command

cvs -H subcommand
cvs --help will tell you how to get a list of what the different subcommands are.

Checking Files Out

When working with CVS, there are 2 copies of files that you need to be concerned with:

  1. The repository, which is visible to everyone
  2. Local copies, which are visible to you

Before doing anything else, you'll need to checkout a local copy of the repository files. Here's an example:

$ cvs checkout mymodule
cvs checkout: Updating mymodule
U mymodule/file1

$ ls
total 1
   1 mymodule/

So what just happened? "mymodule" is a module in the repository. Checking the module out placed a local copy in the current directory. Changes can be made to files here, then put back (committed) to the repository.

Modules are really just directories underneath $CVSROOT. In other words:

total 2
   1 CVSROOT/     1 mymodule/

CVSROOT contains configuration and administrative files used by CVS. We won't worry about that now.

Editing Files

Editing files is easy - once you have local copies, just edit them. None of your changes will be visible to other users until after you've committed them.

If you mess up a local copy of a file, starting over is easy. Delete the file, and use cvs update to get a fresh copy from the repository.

Refreshing Local Copies

If you're working with a group of developers, remember that they're making changes too. Periodically, you'll want to update your working copies. This is done with the cvs update command.

$ cvs update -P -d
cvs update: Updating .
U file1

Above, we see that someone had modified file1, and the copy in the current directory was out of date; cvs updated file1 to the current version. The flags to update are optional. -P "prunes" directories that are empty, and -d tells cvs to include any new directories that aren't in your local workspace (the default behavior is only to include directories that you have checked out). Once you have a local copy, cvs checkout and cvs update -d are more or less equivalent.

update can also take arguments, if you want to update specific directories, or specific files with a directory. If no arguments are given, cvs recursively updates the directory tree rooted at the current directory.

Seeing What's Changed

To see if someone has changed a particular file, use cvs status.

$ cvs status file1
File: file1             Status: Up-to-date

   Working revision:    1.2     Thu Oct 10 14:49:15 2002
   Repository revision: 1.2     /home/srevilak/c/mymodule/file1,v
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)

"Up-to-date" means that the file is current.

To get a quick look at everything, the following command is handy:

$ cvs -n update

The -n option tells cvs "don't change the disk". Where local files don't match the repository copies, you'll see the name of the file and a status code (M for locally modified, ? for something that's not in the repository, and so fourth).

Committing Changes

Okay, you've done some work and you're happy with the results. To incorporate your changes into the repository, use cvs commit.

$ cvs commit filename

CVS will invoke CVSEDITOR so that you can make comments. Once you quit the editor, the changes will be put back into the repository.

Commit comments should be a short description of what you did, enough to allow other developers to look at the file's log and get a sense of what's been done to it. The GNU folks have an entire article dedicated to the subject of documenting changes: http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs.

Adding Files and Directories

Files and directories are added with the cvs add command. To add a directory:

mkdir newdir
cvs add newdir

To add a file

# create the file, edit it
cvs add newfile
cvs commit newfile

To add a binary file

cvs add -kb newfile
cvs commit newfile

-kb tells cvs that the file is a binary file, and that it shouldn't try to expand tags (such as $Id$.) that appear in the file's body. CVS understands many of the same tags that RCS does. See http://ximbiot.com/cvs/manual/feature/cvs_12.html#SEC100, or the co(1) manpage.

Merging Revisions

Normally, it's best to edit files in the directory that you're using for checkouts. This way, cvs will automatically take care of merging in changes, just by running cvs update. However, in some cases that might not always be possible.

Hypothetical Situation: you took a copy of Myfile.java home, and did some work on it. In the meantime, your fellow developers have committed changes to the file. The dilemna - you'd like to incorporate what you've done, but your copy of the file is now out of date. Of course, you also don't want to undo work that others have done. Here's a way to deal with this situation.

  1. Find out what revision your copy of the file is based on. This will be the revision number in the $Id$ or $Revision$ tags. If you can't determine the revision, this approach won't work, and you'll need to do a manual merge.
  2. Run cvs update to refresh your repository copy.
  3. Run cvs log MyFile.java (in the appropriate directory) to get the revision number of the copy that you just checked out of the repository.

For the sake of illustration, lets say that the copy of MyFile.java that you were working on at home is revision 1.6, and the current repository version is 1.10.

Copy the MyFile.java that you worked on at home to your checkout directory. We now have the following arrangement:

To pick up the modifications made from 1.7 - 1.10, you need to merge:

cvs update -j 1.7 -j 1.10 MyFile.java

In cvs-speak, this means "take the changes from revision 1.7 through revision 1.10, and apply them to the local copy of the file." Assuming that there were no merge conflicts, examine the results:

cvs diff -w MyFile.java

Make sure it compiles, then commit.

If things didn't go well, you'll need to examine the results and resolve any conflicts that happened as a result of the merge.

On a related note, update -j ... can also be used to back out a bad commit, simply by reversing the revision order.

Resolving Conflicts

Eventually, something like this will happen:

$ cvs commit foo.java
cvs commit: Up-to-date check failed for `foo.java'
cvs [commit aborted]: correct above errors first!

Here, you've made changes to the foo.java, but someone else has already committed a new version to the repository (eg - the repository version has a higher number than your local copy). Before you can commit the file, you'll need to update your working copy.

If you and the other developer were working on different areas of the file, cvs is pretty intelligent about merging the changes together; it might see that the last set of modifications are in lines 75-100, and your changes are in lines 12-36. In this situation, the file can be patched and your work is unaffected.

However, if the two of you changed the same area of the file it's possible to have conflicts:

$ cvs update foo.java
RCS file: /home/srevilak/c/mymodule/foo.java,v
retrieving revision 1.1
retrieving revision 1.2
Merging differences between 1.1 and 1.2 into foo.java
rcsmerge: warning: conflicts during merge
cvs update: conflicts found in foo.java
C foo.java

Oh dear! What do we do now? The answer is "fix the merge". Two things have been done to help you with this.

  1. A pre-merge copy of the file has been made.
    $ ls -a .#*
       1 .#foo.java.1.1
    However, being a dotfile, it's presence isn't immediately obvious
  2. cvs has inserted a conflict marker in your working copy.
    <<<<<<< foo.java
      static final int MYCONST = 3;
      static final int MYCONST = 2;
    >>>>>>> 1.2

The conflict lies between the rows of greater than and less than signs. The thing to do now is decide what version is right, remove the conflict markers, and commit the file.

Backing out a Bad Commit

Let's suppose that you've commited a file, but this ended up breaking something horribly. Here's how to undo your commit:

  1. Get the version number from after the commit. You can use an $Id$ tag within the file, or cvs status. Let's say that the new version is 1.5.
  2. Get the version number from before the commit. Typically, this will be one lower than the current version. Let's say that the old version is 1.4.

Now do this:

cvs update -j 1.5 -j 1.4 filename
cvs commit filename

The above is an example of a merge. You've asked cvs to take the difference between versions 1.5 and 1.4 and apply them to your working copy. The ordering of version numbers is significant - think of it as removing changes, or going backward in version history.

Deleting Files

To get rid of files, use cvs delete:

rm filename         # must remove working copy first
cvs delete filename
cvs commit

CVS uses a "lazy" system for file deletion; delete just changes the way that the file is stored in the repository. It's still possible to undelete the file, or to check out revisions that existed before the file was deleted. However, the file will no longer appear when you do checkouts or updates.

Because of this, it's not possible to delete a directory entirely. However, one can use the -P flag with cvs checkout and cvs update to prevent empty directories from being retrieved.

Other Useful Commands

There are a variety of other useful cvs commands. Here are a few examples:

cvs diff filename Shows differences between your local copy of filename and the repository version that filename was based on.
cvs diff -r 1.2 filename Shows differences between your local copy of filename and version 1.2 of filename.
cvs diff -r 1.2 -r 1.3 filename Shows differences between versions 1.2 and 1.3. (regardless of what version your local copy is).
cvs log filename Show the commit log for filename (like rlog does with rcs).
cvs annotate filename Shows each line of filename, prefixed with the version number where the line was added, and the name of the person who added it. Useful for seeing who made a particular set of changes.


Branching is a process that allows different versions of a file to be developed in parallel. The cvs manual gives a visual representation here: http://ximbiot.com/cvs/manual/feature/cvs_5.html#SEC60.

[srevilak - I'll hold off on this section until it's needed. Why complicate things prematurely ;]

$Id: cvs.html,v 1.10 2009/07/17 01:13:03 srevilak Exp $