CVS Instructions for CS 597b, Fall 1999

by Ed Felten, October 1999
For a more comprehensive CVS manual, see

Getting Started

To get started, set the following environment variable:
% setenv CVSROOT /proj/sip

Now go into a directory where you want to do your work, and type
% cvs checkout cs597b
This should create a directory subtree called "cs597b", and fill it up with files. The subtree created by this command is your private working copy of the shared files.

Sharing and Synchronization in CVS

CVS keeps a copy of the tree in its repository. (It also keeps a full history so we can revert any file back to any previous version.) In addition, each of us will have his or her own private working copy of the tree. We will do our editing in our own private copy, and from time to time we'll use CVS commands to synchronize our private copy with the repository.

CVS does not enforce locking. Instead, it hopes that we won't make conflicting updates to the same file. If it does detect a conflict, it will notify us and we can clear up the conflict manually. (In my experience conflicts are rare, and are easily fixed.)

You'll usually run CVS commands with your current working directory set to the root of your private working copy of the CVS tree. In general, CVS commands apply to the current directory and all subdirectories (recursively).

A Typical Editing Cycle

Suppose your working copy is up-to-date, and you want to make some changes to the files and then resynchronize your private working copy with the repository. Here's what you do:

First, do your editing in your private copy. Change whatever you want. When you're done editing and are ready to commit your changes and resynchronize, go on to the next step.

Now you're ready to resynchronize. You've made some changes in your private copy, and there might be some changes in the repository (because other people committed their changes since you last synchronized). The synchronization process propagates these changes in both directions between your private copy and the repository, making sure that both sides end up with the newest copy of everything. This takes a few steps, but they're pretty simple.

One thing to note about synchronization is that CVS is smart about handling multiple changes to the same file. If multiple people make changes to the same file simultaneously, CVS will merge all of the changes together so that a single version results, containing all of the changes made. (A conflict results when CVS can't figure out how to do the merge.)

Before resynchronizing, make sure that everything fits together properly in your private copy. If you're working on code, make sure it builds. If you're working on HTML, view it in your browser to make sure it looks OK and the links aren't broken. (You don't want to check in a totally broken version.)

The first step in resynchronizing is to make sure there are no conflicts. To do this, type the command
% cvs -nq update
(-n means "don't do anything, but tell me what you would have done", -q means "be less verbose than usual") The output will be a list of files, one per line, with a one-letter status code for each file at the beginning of the line. A status code of "C" means there is a conflict. If this happens, find a CVS guru who can help you figure out what to do; but it will happen very rarely.

Assuming there is no conflict, the next step is to propagate changes from the repository into your working copy. This will take all of the changes that have occurred in the repository since your last synchronization, and merge them into your private copy. This will happen without any conflicts (because you just checked for conflicts in the previous step). To do this, type
% cvs update -d
(-d means "include changes that involved creating or deleting a directory")

Now make sure everything still works. If something doesn't work, fix the problem.

Finally, you need to propagate your changes into the repository. To do this, type
% cvs commit

Now you're synchronized. You can repeat the edit/synchronize cycle as often as you like. Generally, you'll want to synchronize every time you have a version that you want to save for posterity.

Adding Files to the Repository

To add a file to the repository, follow these steps:

First, create the file in your private working directory.

Next, type % cvs add .

Now, follow the instructions for "A Typical Editing Cycle" above. When you do the "cvs commit" step, your file will be added to the repository.

Other features of CVS

CVS can do many more things, which you can learn about on an as-needed basis. (Or see the full CVS documentation.)

Good luck!