CVS Guide


As you probably have heard, NachOS is a very complicated project involving thousands of lines of code. Throughout the quarter, you will be writing and modifying lots of it. Since you will be working in groups, at times it will be hard to remember who changed what in which files. Anyone who had survived BunnyWorld (or had written any other significant project in a group) remembers the pain of integrating different versions of code.

CVS stands for Concurrent Version Control, and it is a widely used version control system on UNIX platform. It is a command-line system, but it is also integrated into Emacs (and hence XEmacs) very well, so you can diff the files and directories from within Emacs.

Why Use CVS?

We do not require that you use CVS. We will not answer any but the most trivial support questions about it, since we aren't CVS experts. However, we provide this information as a service because, in the opinion of some of the TAs, it was very useful and helpful without very much trouble to learn how to use it.

If you use it right, it could greatly reduce your integration time, along with backing up all of your changes as you go. Every group member works on their own separate version of code, and after a feature is complete it is integrated into the master repository.

Where to get Info?

The best place to look is in the CVS manual. You can get to it in UNIX by typing

mythXX:~> info cvs

CVS Setup
  1. For CVS to work, you need a repository, which is where the master version of all of your files will be stored. Pick a group member (usually with the largest disk quota).
    That person creates the directory (usually called cvsDir) and makes it readable to all of his group members:
    mythXX:~> mkdir cvsDir
    Give read/write permissions to all of the group members:
    mythXX:~> fs sa cvsDir userid1 write
  2. Setup the environment variable in everybody's account pointing to the repository
    Say the repository is in ~commie/cvsDir
    Add the following line to the top of everybody's .login file under the Environmental Variables heading:
    setenv CVSROOT ~commie/cvsDir/
  3. CVS assumes that the default editor is vi. Most people at Stanford feel more comfortable using Emacs. If you want to have Emacs be your default editor, you need to add the following line to you .cshrc file:
    setenv EDITOR "emacs"
  4. You need to completely logout from the machine and log back in so that the new environment variables are used.
Creating the Project
  1. The easiest thing is to copy the contents of the project from our directory into one of the group member's directories. For example, it could reside in ~commie/cs140/base/.
  2. Create the project and add all of the files to the CVS repository:
    mythXX:~/cs140/base> cvs import -m "nachos proj" base commie start
    This creates a subdirectory code in the CVSROOT directory, with the tag commie (don't worry about the tag).
  3. Now there is a nachos project in the master repository under the name BASE. Everybody in the group (including the owner of CVSROOT) needs to checkout the project from CVS.
    CD to the directory where you want it to be:
    mythXX:~> cd cs140
    Checkout the project:
    mythXX:~/cs140> cvs checkout base
    This should create a copy of the codebase in everybody's account.
  4. Additional information could be found in info cvs following the following tree:
    info cvs -> Starting a new project -> Setting up the files -> From Files
    You can customize your project name and do other fancy stuff if you are planning on using CVS in the future and want to have a nice directory structure.
Using CVS
  1. Type cvs update at the root of the project in the beginning of every programming session to synchronize the project with the current master copy.
  2. To add new files and directories, type
    cvs add <filenames>
  3. After finishing a feature or fixing a bug, type
    cvs commit
    to commit all the changes in the current directory or
    cvs commit <filename>
    to commit individual filename(s).
  4. You can get additional information by typing
    cvs help
    cvs <command> --help
    for each command.

Integration happens for free during the commit process. CVS diffs the newly committed file with the previous versions, looking for changes and incorporating those changes into the repository. Your partners will get the new changes with the cvs update command, which will change the local checked out copy to reflect the repository.

However, at times CVS cannot merge things for you when you're trying to update. This typically happens when your partner has committed a new version of the file since the last time you've updated, and you've also edited the file (so that CVS sees two sets of changes since the last version in the repository, and doesn't know which one supercedes the other). In such cases, it will flag the conflicting changes with <<<<<<< and >>>>>>>>. You will have to merge these sections by hand. This is the trickiest part, so make sure you have both people present when you are solving a merge conflict.

Please note that in order to prevent such conflicts from appearing in the repository, CVS will sometimes force you to update before you commit.


I would highly recommend reading the CVS website (or info cvs) for basic information, looking at the following commands:

checkout, update, commit, add, remove, diff.

It is also a good idea to create a dummy project, add it to the repository, check it out, do some changes and commit them. Then a partner should make sure he can update and that the changes show up in his or her directory.

I would also recommend playing with CVS from inside XEmacs as well. You can get to it from Tools/VC menu, and you have options like Diff buffers, Diff Directories, Visit Other Version, etc.

I personally have found Visit Other Version along with Diff buffers extremely useful. There is even a nice color merging tool within XEmacs as well, very similar to Visual SourceSafe.

Try it out!

Written by Toli Kuznnets , edited by Yu Ping Hu for some clarifications.
Last modified: Mon Oct 2 17:19:13 PDT 2000