Systems Programming

Using CVS

This document adapted from Lyn Turbak's CVS reference for CS251.

1 Overview

Shared programs in this course, including class projects, is under control of a version management system named CVS (Concurrent Versions System). CVS is a standard way to control versions of files in software projects.

CVS has some very sophisticated features for allowing multiple users to work on a shared set of files without stepping on each others toes. In Systems Programming, we will be using a subset of these features to distribute program files and bug fixes and to share code. This will make it easier for me to to post code and bug fixes, and will make it easier for you to download and upload code for your projects. You should never have to copy files from the ~systems directories on puma; instead you will use CVS commands to install the files you need (see Section 3 for details).

2 Installing Your Local CVS-controlled Filesystem

Puma and all the Linux cluster machines have been configured to run CVS. In order to use CVS in this course, you will have to install a local CVS-controlled cs249 filesystem in your account. To do this, carefully follow the steps below. You only need to perform this installation once. Once it is installed, you can use your local cs249 filesystem throughout the rest of the semester.

  1. Set the CVSROOT variable in your shell. If you are configured to use the bash shell (the default), add the following line to the end of your ~/.bash_profile file:
    export CVSROOT=:local:/home/systems/cvsroot
    After this step, log out of your session and log back in so that the CVSROOT variable is set correctly.

    If you are using the csh shell, you will add this line to your .cshrc file:

    setenv CVSROOT :local:/home/systems/cvsroot
  2. I have created a group on the department server for our use, and you are all members. It's called sysstu. It will be helpful if files and directories we add to the repository have this group. To ensure that this happens, you can either run the newgrp command or add this line to your ~/.bash_profile:
    newgrp sysstu
  3. You could also set the environment variable CVSUMASK to be 0002.
  4. You can take care of all the above items by adding this function definition to your ~/.bash_profile file: 
    
  function cvs-systems () 
  {
          export CVSROOT=:local:/home/systems/cvsroot;
          export CVSUMASK=0002;
          newgrp sysstu;
  }
    You cannot put spaces around the = above: it's a bash thing.

    Then, whenever you work on your projects for this course, you can type cvs-systems to your shell, and everything will be set up.

  5. We will install the CVS-controlled CS249 directories inside your existing cs249 directory. The installation will automatically create the necessary subdirectories directories; you should not create them by hand. You can install the CVS-controlled cs249 directories by executing the following commands in the Linux shell:
    cd ~/cs249
    cvs checkout -d project archive/spring2008/project

    Executing the cvs checkout command (which can be abbreviated cvs co) will create a project directory in your cs249 directory and will populate it with some subdirectories. As these subdirectories and the files they contain are installed, feedback will be provided on the console as to what is being installed.

    When the checkout process finishes, the directory ~/cs249/projects will contain your local copy of the CVS-controlled course projects filesystem. Each CVS-controlled directory in this filesystem contains a subdirectory named CVS that contains important administrative information for CVS. YOU SHOULD NEVER DELETE OR MODIFY ANY DIRECTORY NAMED CVS, NOR THE CONTENTS OF SUCH A DIRECTORY.

3 Using the CVS-Controlled Filesystem

Here's the really cool part. Whenever you begin to work on an assignment on any given day, first execute the following commands in a Linux shell (preferably a shell in an EMACS bufffer):

% cd ~/cs249/projects
% cvs update -d .

This will automatically update your local copies of the cs249 filesystem with any modifications, new files, and new directories from the repository. In particular, any files that have been posted since you last worked will be automatically added to your local cs249 filesystem, and any bug fixes will be automatically installed!

CVS recognizes when you have locally modified one of the CVS-controlled files, and will do its best to merge any modifications from the repository with your local modifications. It usually does a good job. Every once in a while it can't figure out how to merge displarate changes; see Section 4 below for how to deal with conflicts.

When you do the update, CVS will tell you what it did to each file. It prints out a single letter before each filename that tells the action it performed on that file. Here's what the most common letters mean:

The reason I suggest running updates in an emacs buffer is that often these indications will scroll off the screen quickly. You should always check for conflicts by scanning the cvs output for C. The earlier you detect the conflicts, the easier they are to fix.

4 Conflicts

When performing cvs update -d gives you a conflict (denoted by the letter C), it means that CVS could not figure out how to merge modifications to the repository with your local modifications. When it can't figure out what to do, it inserts text that looks like:

<<<<<<< driver.c
your local text
=======
text from the repository
>>>>>>>
In this case, you need to manually edit the text between the <<<<<<< and >>>>>>> to be what is correct. (And you must delete the <<<<<<<, >>>>>>>, and =======, too.)

For more details about conflict resolution, consult the online documentation described below. Thankfully, conflicts are rare, and you usually don't have to worry about them.

5 Uploading your Changes

There are two ways that you will contribute changes to the course project: After checking out files, you have your own local copy of all the course project files. You are free to experiment and modify them as you see fit. You can then throw out your changes, keep them private, or update the central repository so that everyone else will see your changes on their next cvs update The cvs commit command sends local changes to the central repository atomically. The easiest way to use this command is to cd to a shared directory under which all the changed files reside, and type
% cvs commit -m "change description" .

The change description is a comment in which you summarize the nature of your changes. This comment becomes part of the file's history (which can be printed out with cvs status). All changed files under the current directory (including any subdirectories, and recursively and subsubdirectories, etc.) will be copied back up to the server. Any new files you created will not be copied up. If you need to add a new file or directory, f to the repository, you type cvs add f. Then, the next time you commit changes, the corresponding entry will be added to the central repository.

Warning: Renaming files is a messy, error prone operation under CVS, and we don't want to do it. Therefore, do NOT add local test files or random explorations to the course repository. Keep them private. It is best if we decide on ALL SHARED FILE NAMES as a group.

6 Documentation

For more documenation about CVS, consult the on-line manual at

http://www.cvshome.org/docs/manual/index.html
(This is linked from the CS249 Resources page.)

Note that you are only using a very small subset of the features in the manual. The only CVS commands you should need are:




Author: Mark A. Sheldon
Modified: 17 April 2008