Design Rationale Group: CVS HOWTO

(adapted for DRG from the HAL CVS Tutorial by Michael Coen and company)

This HOWTO contains a brief tutorial on CVS, the Concurrent Versions System. CVS is the source code control system used in DRG.

Vital Statisitics For Experienced Users

(NB. You must use SSH for remote CVS. Make sure your CVS_RSH environment variable is set to ssh.)

Local CVSROOT: /projects/drg/CVSROOT
Remote CVSROOT: :ext:<login>@fracas.ai.mit.edu:/projects/drg/CVSROOT
Module: drg, which contains ASSIST, ASSISTANCE, and the Sketch Toolkit.

Table of Contents

Basic Concepts
One page reference guide
Be a nice person when you commit! Read this first!
Other information
Manuals and Web Resources
PCL-CVS: An Emacs user interface for CVS
Contact information
Frequently Asked Questions
Troubleshooting

Basic Concepts

 CVS is the source code control system used in DRG. It lets people collaborate on software projects by keeping track of versions of source files and synchronizing individuals' copies of the source tree. (CVS is essentially a multi-user front-end for RCS, if you are familiar with RCS). In the fine tradition of UNIX tools, CVS has a cryptic interface, unintuitive behavior, and a million rarely used features.

CVS stores all of the source files associated with DRG in a central repository. Users should never edit files in the repository, or even worry about where the repository is located. Instead, they interact with the repository via CVS, usually through a command-line interface.

With CVS, you can checkout whole modules (directories) of files, edit them, then commit them your changes into the repository when they compile properly. You can update your copy of the files to merge in the changes others have committed to the repository.

An important concept is a conflict. This happens when both you and another person have changed the same part of the same file. When you update your copy of the file, CVS detects this and will include both copies of the conflicting text in your file. You will then have to edit the file by hand and include the appropriate version of that text. (More about this below.)

CVS keeps versions of every file in the repository. When changes to a file are committed, the file is assigned a new version number (usually 1.n+1, where 1.n was the most recent version.) It's possible to check out an old version of a file in case you want to undo some changes you've made, but things get a little complicated so I won't cover the details here.

Files and directories must be explicitly added and removed from CVS control. By default, new files you create are not in CVS control, even if they are in a directory that is part of the repository. You must add them to CVS before others will get a copy when they update.

Since CVS stores files by diffs, it is customary to control only source and configuration files and not to control object files (or other automatically generated files). Therefore, do not add .class files or .html files generated by javadoc into the repository.

The repository for DRG is located in the directory mentioned above. You should only have to worry about it when you check out the files for the first time. Afterwards, CVS will keep track of the repository's location. Please don't edit files in the repository directly; in fact, they are kept read-only to prevent this from happening accidentally.

One page reference guide

Here is a one-page reference guide to basic tasks in CVS. It is kept separate so you can print it out for reference.

Be a nice person when you commit! Read this first!

It's important to say a few words about commit policy. When you commit code it's a signal that you are ready to share your changes with the world. It's likely that some of your changes will break other people's code, since they also have changes they haven't committed yet. But doing the following will minimize the bad effects and you will be considered a nice person :)
  • Update frequently. CVS will force you to update before you commit but if you update a lot you can deal with the changes a little at a time instead of all at once.
  • Commit when you've made changes that affect others' code, such as changes to APIs or functionality, or fixed bugs.
  • Test your changes to your satisfaction before you commit. If you commit really buggy stuff people will be annoyed.
  • You can hold off and commit many changes at once, but then everyone else will be really annoyed, because they will have to integrate all your changes at once with their uncommitted code. If you have made a lot of changes it's best to coordinate the group first to determine the best time to do things.
  • Never commit code that doesn't compile. In fact, right before you commit, do a cvs update and make clean; make to rebuild from scratch. Fix any compilation errors and repeat (including the update) until you get a clean compile.
That's it. I don't think there are a lot of dependencies right now but DRG gets bigger and more integrated things will get more complicated ...

Manuals and Web Resources

  • cvs --help-commands will list all of the CVS commands available. cvs <command> -h will list help specific to command.
  • The CVS Manual, an HTML version of the texinfo manual for CVS.
  • CVS FAQ-O-Matic, an extensive CVS FAQ that covers a lot of advanced topics.

PCL-CVS

 PCL-CVS is an Emacs user interface for CVS. Most every common CVS command can be performed in an emacs buffer listing files in your working copy. To run PCL-CVS, type

M-x cvs-examine

and enter ~/drg when prompted for a directory. It will display the status of the files in your working copy in a buffer. It will only show files that need updating or are locally modified, so if no files are displayed, that means your copy is in sync with the repository.

You can access commands from the CVS menu in the Emacs menubar or via keyboard shortcuts documented in that menu. Common shortcuts are:

e re-examine working copy and update buffer
O update working copy from repository
c commit changes to repository
a add file or directory
= diff local and repository versions of a file

Contact Info

These folks have experience with the many, many quirks of CVS and are familiar with the DRG repository, and can be consulted if help is needed.

Frequently Asked Questions

 To be filled in as questions arise.

Troubleshooting

 To be filled in as cases arise.

mark a. foltz (mfoltz@ai.mit.edu)
$Id: DRG-CVS-HOWTO.html,v 1.2 2001/04/23 23:37:53 mfoltz Exp $