SENS config-mgmt: How to use CVS

Students new to our project will most often begin by using or modifying source code that was developed by someone else. As a rule, we are very careful to organize all of our source code into CVS modules, each of which is a Unix directory that contains source files and sub-directories. In general, we create one module for each application or software library that we develop. See SENS Modules for a catalog of the current modules under development.

Each module is stored in a central repository, also called a source tree. In order to use or modify the sources within a module, a developer must first check out a working copy of the module from the central repository. The diagram below illustrates the difference between a source tree and a working copy:

Here, the central repository contains a directory called proj, which contains files and subdirectories. Each file under proj is an RCS file (i.e., a file whose extension is ,v). A user, Joe, would not edit these files directly, but rather would check out his own working copy, which would be located (for example) in /user/joe/proj. Note that /user/joe/proj contains files and subdirectories that correspond to those in proj; however, the files are not RCS files. Moreover, each directory in the working copy contains a directory called CVS, which contains information used by CVS to keep the working copy in synch with the source tree.

CVS is a huge system with lots of command-line options; however, we usually only need a small subset of this functionality to manage sources. There are five commands you need to know:

cvs checkout
creates a local copy of a source tree in your directory. You need to do this only once. The local copy will be placed in your current working directory when you execute the command.
cvs add
(assuming you have created a new file in your local copy), lets you add this new file to the source tree.
cvs commit
(assuming you have modified one or more files in your local copy), lets you commit these changes to the central repository.
cvs release
releases your checked out version of the module. It's nice to release these modules when you're not going to edit them for a while. Just be sure to commit any changes prior to releasing.
cvs update
(assuming someone else has committed changes to the central repository), updates your local copy to reflect these changes.
The cvs command also takes a parameter that identifies the location of the central repository. I find it useful to create a mnemonic alias that invokes cvs with the proper directory. This strategy is particularly nice if you use cvs in multiple projects. For example, I would suggest aliasing the word 'research' as follows:

alias research="cvs -d /user/stire/Mastermind/Tree"

This will let you type:

research checkout PTL_DNF

to create local copy of the module in your working directory. Likewise, you can type:

research commit
research update
research add file

where file is the name of a new file that you want to add to the repository. I would suggest putting the alias in your .profile.

What follows is a usage scenario. Let's say that you and I both have local copies of the directory PTL_DNF that we created by doing:

research checkout PTL_DNF

If I make a change to the file foo.cc in my local copy, I can type:

research commit foo.cc

or just:

research commit

to publish my local changes in the central repository. To get these changes, you would then need to type:

research update

to update your local copy with my changes. If I add a file bar.h to my local copy, I would do the following:

research add bar.h
research commit

Note that the central repository is not actually updated to reflect the addition until you do the commit.

If I add a new directory to the central repository, then you will need to type:

research update -d

as opposed to just:

research update

Finally, to release a module, cd into the directory that contains the root of the module (PTL_DNF in this example) and then type:

research release -d PTL_DNF

The ``-d'' says to delete the directory PTL_DNF after the module is released.
Kurt Stirewalt
Last modified: Thu May 24 19:33:22 EDT 2001