Project Management Using Concurrent Versions System (CVS)


Overview

The goal of this page is to describe the basic use of CVS and to describe how CVS is used in the development of the Interactive Rendering and Image Segmentation (IRIS) project.  This page does not describe the full functionality of CVS but serves as a guide for developers of the IRIS system.  Complete documentation and a listing of frequently-asked-questions regarding CVS can be found at http://www.loria.fr/~molli/cvs.

CVS can best be described as software that helps manage software development and software releases.  In particular, it is useful when there is concurrent editing of source files by multiple software developers.

The way CVS works is as follows:

A central copy of project files is maintained.  This is called the main repository.  Each developer creates his/her own personal copy of project files (a workspace) from the main repository.

When a developer decides to modify a file, he/she simply modifies the file as normal.  Once modification begins, the file is considered "checked out" in that the file differs from the copy in the main repository.

When a developer has decided that the changes he/she has made have progressed to a point that all the other developers should be made aware of the changes, the developer checks the appropriate files back into the main repository.  In general, the main repository is a stable version of the software so developers usually verify that the changes they are about to check in are "correct" and will not break the software.  At a bare minimum, the checked in files should allow the software to build without errors.

At times a developer may wish to "update" his/her copy of the project files with changes that other developers have incorporated into the main repository.  (A developer usually does this prior to checking in modifications in order to verify that his/her changes are not going to break the repository version.)
 

Getting Started: Creating a Personal Copy of Project Files

To create a personal workspace for your deverlopment, follow these steps:
    1. Go to the directory where you wish to create your workspace.
    2. Run the script `irishier' located in:    /afs/cs.unc.edu/project/courses/comp145/s99/iris

Here's an example of what should happen in a UNIX environment.
    bardeen(10)%  cd comp145                                                                               (Step 1)
    bardeen(11)%  /afs/cs.unc.edu/project/courses/comp145/s99/iris/irishier              (Step 2)
    Create a IRIS hierarchy starting at /afs/cs.unc.edu/home/wynn/comp145? (y/n) y

    MAKING DIRECTORIES...

   cvs checkout: Updating doc
    cvs checkout: Updating src
    U src/Makefile
    U src/main.cc

    COMPILING...

    ~/comp145/myiris/src ~/comp145
            /bin/CC -c -g -I. main.cc
    CC: "main.cc", line 7: warning: Function 'main' must return type 'int' (anachronism) (312)
            /bin/CC -o iris main.o
    ~/comp145

    DONE!
    Have fun!

    bardeen(12)%
 

Modifying Project Files

To modify project files in your personal workspace, simply modify files using your favorite editor.
Once modification of a file occurs, that file is considered "checked out" and will eventually need to be "checked in" in order to update the main repository.
 

Getting Updated Project Files

In order to keep your personal copy of the project files up-to-date with the project files located in the main repository you will want to retrieve updated files from the main repository.

To retrieve updated files, follow these steps:
    1. Go to the directory where you wish to update files in your personal workspace.
    2. a) To update the entire directory type `cvs update'
        b) To update a single file type `cvs update filename'

Step 2a. will walk through the corresponding directory in the main repository and give you updated copies of any files that have changed.  Step 2b. will give you an updated copy of the file you specify.

In either case, 'cvs update' will automatically merge changes in the main repository into your existing source code.  It is fairly conservative in merging two versions of a file.  If cvs is unclear about how a merge should be done, it will flag the changes as follows:
<<<<<<< filename.C
   <old code will be here>
=======
   <new code will be here>
>>>>>>> <version number of updated file>
This won't compile (this is intentional) and you will be required to go in by hand and perform the merge of old code with new code by hand.  Fortunately, cvs marks the region of code you need to be concerned with, so performing the merge by hand is generally not too difficult.

After running `cvs update' a list of files will be displayed, where each file is preceeded by a single character.

Here's an example of what will happen in a UNIX environment.
  shark(15)% cd myiris
  shark(16)% cvs update
  cvs update: Updating .
  M main.cc
  ? iris
shark(17)%

In the above example, the 'M' character means that the file "main.cc" is up-to-date but that you have made modifications that have not yet been checked-in to the main repository for others to see.  The '?' character means that the file "iris" is not under cvs version control.  This is fine since "iris" is an executable and it doesn't need to be under version control.

Characters that may appear before a filename after running 'cvs update' are the following:
    U    file.cc        Your local version of "file.cc" has been made consistent with the version in
                            the central repository.
    M    file.cc        Your local version of "file.cc" has been made consistent with the version in
                            the central repository, but you have modifications you have not yet checked-in
                            to the central repository.
    ?     file.cc        Your local version of "file.cc" is not under cvs version control and does not
                            exist in the main repository.
 

Checking in Modified Project Files

Once you have completed making modification to project files, you will need to check them into the main repository so that others may view your changes.

Before checking in files you should invoke a `cvs update' at the top level of your personal workspace and compile to ensure that checking-in your modifications to the central repository will not break the central version of the code.  If you do check-in broken code that does not compile, other developers will be very, very unhappy when they perform a 'cvs update' and get your broken code.  All concurrent development will be halted until you fix the broken code.  Please be sure to make sure that checking in your modifications will not break the central version of the code and consequently all other developer's code.

After ensuring that checking in your changes will not break the central version, check-in files using one of the following methods:

    Checking in all modified files (recommended)
        1. Go to the top level directory of your personal workspace.
        2. Type 'cvs commit'
        When you commit, CVS will open up an editor (specified by the CVSEDITOR environment
        variable, defaulting to $EDITOR, and finally to vi) to let you enter a log message.  Here is where
        you type a clear, sensical message which explains the changes you are checking in.  Please enter
        a message, and please be clear as this will make reverting back to a previous version of the
        software simpler should the need arise.

    Checking in selected modified files (not recommended)
        1. Go to the directory of your personal workspace which contains the file/directory you would
            like to check in.
        2. Type 'cvs commit dirname' or 'cvs commit filename'
        When you commit, CVS will open up an editor (specified by the CVSEDITOR environment
        variable, defaulting to $EDITOR, and finally to vi) to let you enter a log message.  Here is where
        you type a clear, sensical message which explains the changes you are checking in.  Please enter
        a message, and please be clear as this will make reverting back to a previous version of the
        software simpler should the need arise.
        (This version of checking in files is not highly recommended because if all of the files which were
        modified are not checked-in, after checking in selected files the version of the software that resides
        in the main repository might not correspond to the version of the software that you verified would
        not break the code in the main repository.  Consequently,  only checking in a subset of your
        modified files might result in the code which resides in the main repository being broken even
        though your local copy is not broken.  Be careful if you check-in files in this manner.)
 

Adding New Project Files

To place a new file under cvs version control, type 'cvs add filename.cc filename.h ...'
These files will be added to the central repository the next time you check-in files using 'cvs commit'.