Index: Why CVS | CVS Usage Model | Using CVS | For More Help

Why CVS Instead of RCS

CVS's big benefit over RCS is that it deals with collections of files, called modules, rather than individual files. A module is basically a single subdirectory. However, the module can logically contain another module. You can operate on any arbitrary module subtree. This means that unlike RCS, where there is a separate RCS tree per package or application, a single CVS repository can hold many different and distinct packages. I have set up /home/CVS on one of full-sail's local disks as a repository for all GloMop-related stuff.

CVS takes some getting used to, relative to RCS, because there is no concept of locking. Anyone can check out and work on a module. When changes are committed to the golden repository, most conflicts are handled transparently using rcsmerge; line-by-line conflicts prevent files from being checked in and must be resolved by hand.

CVS Usage Model

Unlike RCS, in CVS the location of the "golden repository" is totally unrelated to the location of your work area where you do development. This is good, because it keeps the repository "out of the way" and you can do development wherever it's convenient. (CVS even provides a way to check files in and out across different machines, as is discussed later.)

Here's how your work session goes in CVS:

You go to your working area (maybe on /tmp on your home machine) and say "cvs checkout module" to checkout some subtree you want to work on.
You do a bunch of development. In the process, you might add some new files to the tree (cvs add) or remove some files from CVS control (cvs remove).
You say cvs commit to commit your changes. If you're lucky, no one else has made simultaneous changes. The next time you or someone else does cvs checkout, they will get the updated files.

Suppose your co-worker tells you "I just made some changes to the 'foo' module, and updated the CVS tree." Here's what you would do:

Go to your work area, where the 'foo' module has been checked out for the last couple of days because you've been working on it.
Say cvs update -d where the -d causes CVS to also create any new subdirectories that have been imported into this module. (By default, only the existing subdirectories of the module, if any, are updated.)
Cvs updates the files that have changed and checks out copies of any files that were added to the module since the last time you updated.

Using CVS

Setting Up

The first thing you must do is set the CVSROOT environment variable to the root of the CVS repository tree, e.g. /home/CVS. (You can also say "-d pathname" with any CVS command to name the tree explicitly, but I recommend the first way.)

If the repository is on a different machine, set the repository name to be something like user@machine:/path/to/repository. (You must have an account on the repository machine for this to work.) Specifically, to get to the repository for the GloMop group, you should set it to username@full-sail.cs.berkeley.edu:/home/CVS (replacing username with your username of course).
You should also set the environment variable CVS_RSH to indicate how CVS should communicate with the server. The best choice is ssh (if you have it); you can also use Kerberized rsh (sometimes rsh and sometimes krsh, depending on the installation), in which case you must use kinit to get valid Kerberos tickets before doing CVS operations.

Adding Files to the Repository

So you want to add your application to the CVS repository. Good! If all of your code is in a single directory that contains no subdirectories, do the following. (Note: Don't do this to a "production" application's repository or many people will be very angry with you. Use the import operation only to add new applications to the repository.)

Go to the directory where all the code files live that you want to check in.
Be sure CVSROOT is set.
Pick a symbolic name for your module. This is the name you will use for checkin, checkout, etc. Most commonly it is the same as the name of the directory containing the files to be added. For example, if your app lives in a directory called "helloWorld", then the module name would be "helloWorld".
Determine which files you really want to check in. (Sometimes you have additional files -- test code, TBD lists, etc.-- that aren't part of the application and shouldn't be checked in.) NOTE: On non-Unix clients, CVS import can only handle text files. This isn't an issue for Unix clients.
Say the incantation:
cvs import -I file modulename initial initial
Each "-I file" is a file you want to ignore (i.e. don't want checked in) as determined in step 4. You can have multiple -I switches. Any files not mentioned by -I will be checked in. modulename is the name you picked in step 3. The last two arguments are the 'vendor tag' (which you don't care about) and the 'release tag'. The release tag can be used to retrieve a particular version of a module symbolically. For example, tagging a stable version as 'release' allows others to use the 'release' tag when checking out to make sure they don't get your development version. The online manual has more about this.

Congratulations, your files now live in the CVS repository. To test whether it worked, try checking out the new module.

If your application directory contains subdirectories, it's a little trickier. You need to check in each subdirectory as a submodule. For example, suppose your app lives in directory 'foo', with subdirectories 'bar' and 'baz'. You would first go into 'bar' and perform the above checkout procedure, naming the module 'foo/bar'. Then do the same for 'baz'. Finally, go up to 'foo', and check in the module named 'foo'.

This somewhat convoluted procedure has two effects:

Modules foo, bar and baz are independent: you can checkout foo/bar or foo/baz independently, without even checking out foo itself.
The hierarchical relationship between the directories is preserved, so that if you do checkout foo, you will get the whole subtree including bar and baz.

Checking Out a Module

This is simple. Go to your favorite working directory (far away from the CVS repository, we hope), and say "cvs checkout modulename". If the module includes nested subdirectories, you will get them automatically.

If you're checking out over a slow network link, you can use "cvs -z 9" instead of just "cvs"; it causes gzip -9 to be run on the server and gunzip on the client automatically.

Adding or Removing Files from an Existing Module

While working in a checked-out copy of some module, say "cvs add filename" to add a new file to the module. (The file must already exist.) Conversely, say "cvs remove filename" to remove a file from the module. (The file must already have been deleted from the working area.)

Committing (Checking In) a Module

When you're ready to check in your changes, say "cvs commit". Like RCS, CVS will fire up an editor so you can type your change comments. When done, checkin will proceed. The environment variable CVSEDITOR controls which editor is used (vi is the usual default).

Bringing Your Working Copy Up-To-Date

Go into the directory containing your working files, and say "cvs update". Any changes made to the module by others since you checked it out will then be reflected into your working copy. It's a good idea to do this frequently, since modules that many people work on tend to change quickly.

Other Help

Try "cvs -H" for a list of CVS options, and "cvs -H command" for help on CVS command command.

See the online manual for more.

Maintainer:

Armando Fox, fox@cs.berkeley.edu