Question:

I want to get involved with Open Source development. It seems that all the Open Source projects use CVS. I've read the Cederqvist, but I'm a bit confused. How about a CVS for Dummies?

Answer:

OK, if you insist.

For those that have not read the Cederqvist.

CVS is the Concurrent Versions System version control tool. Its goal is to allow multiple developers to work on the same code base with a minimum number of conflicts and a maximum amount of productivity. Like other source code control tools, CVS is Repository based and uses the check out, check in model.

The Repository contains a complete record of all changes to the code base. The Repository can be local or remote. For remote Repositories, CVS supports several client/server access methods.

A developer checks out a copy of the code base to a local work area. CVS calls this work area a Sandbox. The developer checks in the changes from the Sandbox to the Repository. CVS calls this committing the changes.

The Sandbox is a directory tree. Some of the directories will contain source code. Others are owned by CVS and contain control files. The CVS owned directories are named CVS and CVSROOT.

CVS differs from most other source code control systems in that files are not locked when a developer checks them out. This means a second developer can check out a file after the first developer, make changes and commit the changes the Repository before the first developer. This means that the first developer is now working with an older version of the source code. CVS solves this problem for the first developer by automatically merging Repository changes into the Sandbox, when requested. If there are conflicting changes, they will be flagged. In practice, conflicting changes do not occur all that often.

Select a CVS Client.

Install the CVS Client.

• Unzip the zip file to a work directory, preserving paths.
• Move to contents of the bin directory to a directory in the PATH.
• Move to contents of the book directory to a directory in BOOKSHELF. Run the install.cmd script from the installation directory to create Desktop objects for the INF files. Delete the script after you have run it.
• If you use the info reader, move to contents of the info directory to your info directory and add an entry for the CVS info files to the dir file.
• If you use the man reader, move to contents of the man directory to your man1 directory.
• You can ignore the contents of the scripts directory for now. The scripts are for server side features.

The folks from Netlabs also provide a nice CVS front-end NOSA . This front-end supplies a set of WPS objects that make it easy to access to the CVS Repositories for the various Netlabs projects.

First Time Setup.

If you haven't already do so, define a home directory. From the command line:

  D:
  mkdir \home
  SET HOME=D:\home

  SET HOME=D:\home

Create the file D:\home\.cvsrc containing:

   cvs -z3
   update -d

CVS creates temporary files and expects TMP to be defined. This should have happened when you installed Warp. If you point TMP to a RAM disk and don't have a lot of RAM, you may have problems with large Repositories.

Creating a New Sandbox

The examples that follow refer to the excellent XWorkPlace project. The process for other projects is similar.

• Create the Sandbox directory with:

    cd \projects
    mkdir XWorkPlace
    cd XWorkPlace
  

• Determine the CVSROOT value and login password. These should be documented at the project website.

  The XWorkPlace website states that the CVSROOT value is:

    :pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace
  

  and the password is:

    readonly
  

  The CVSROOT value defines the access method, the user name and the Repository location. The pserver access method and user name are typical for Repositories that provide read only access.

• Point at the Repository with the command:

    set CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace
  

  Once the Sandbox is populated, the Repository location is recorded in the Sandbox and the CVSROOT environment variable will be ignored for most commands.

• Log in to the Repository with the command:

     cvs login
  

  Enter the password when prompted.

  You only need to log in once for each Repository you access. CVS records the login password in d:\home\.cvspass. Notice that you log in to a Repository not a project. Although not the case for Netlabs projects, a Repository may contain many projects.

• Do the first time checkout to populate the Sandbox with the command:

      cvs co .
  

  where co is an abbreviation for checkout. That's a period after the co and it is required. For the checkout command, the period represents the default module, not the current directory. With CVS, you check out modules, not directories. Modules allow the Repository organization to differ from the Sandbox organization. Usually a module represents a single directory tree in the Repository, but this is may not be the case for complex projects that have grown over time.

  Many MB later you will have a Sandbox populated with the XWorkPlace code base.

  Once you have populated the Sandbox, it's best to think in terms of directories and forget about modules. When working with an existing Sandbox, the commands take directory or file arguments. Also, most CVS commands are recursive by default. A single command will process all the subdirectories in the Sandbox.

Reviewing Changes

After you have made some changes, you might ask yourself what did I do? You can review your changes with command:

  cvs -q di

Updating the Sandbox

After you have played in your Sandbox a while, you will probably want to bring your Sandbox into sync with the Repository. Update your Sandbox with the command:

  cvs -q up

• U means CVS replaced a file you did not change with a newer version.
• P means CVS patched a file you did not change to a newer version. The effect is the same as an update. It just happens faster.
• A means you added the file with cvs add, but have not committed the change.
• R means you removed the file with cvs remove, but have not committed the change.
• M means you have modified the file. If the Repository is also modified, CVS will display an additional message when it merges the Repository changes.
• C means you have modified the file and there were changes in the Repository and that conflicts were detected during the merge. You will need to edit the file and resolve the conflicts. The conflicts are marked so you can find them.
• ? means CVS found a file in your Sandbox that is not in the Repository and that is not configured to be ignored.

Updating the Repository

Eventually you may be given write access to a Repository and you will want to commit your changes to the Repository. Commit your changes with the command:

  cvs ci -m"Added foobar recovery support"

Some Handy Commands

Like all applications with a unix heritage, the cvs command has a multitude of options and switches. Here are a few obvious and not so obvious combinations that you may find useful.

•   cvs
  

  lists an overview of the available command line help options.

•   cvs up -?
  

  lists the options available for the update command.

•   cvs co -c
  

  lists the content of the modules file.

•   cvs -q up -l Changelog
  

  quickly updates just the Changelog file.

•   cvs -nq up
  

  does everything an update would do without changing any files in the Sandbox.

•   cvs -nq ci -m"Testing"
  

  does everything an check in would do without changing any files in the Repository.

Additional References

There are a vast number of CVS references on the web. The core reference is Per Cederqvist's Version Management with CVS. Karl Fogel's Open Source Development with CVS does a good job of explaining why CVS works the way it does. Of course, a visit to The Home of CVS is always a good plan.

SCOUG, Warp Expo West, and Warpfest are trademarks of the Southern California OS/2 User Group. OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.