Using CVS to manage your files

 

CVS stands for 'Concurrent Versions System', which is another way of saying that multiple users can check out private copies of files from a central repository, each can work on them at the same time (this is the 'Concurrent'), and when they're finished, check them back into the central repository, where they are assigned a unique version number (this is the 'Versions' part of it). Any other CVS user can then integrate those changes into his/her own version by using a simple command (this is why it's called a 'System'!). If two or more users happen to have modified the same section of the file, CVS is often able to figure out how to combine them all. If it can't, it tells you, so you can do it by hand.

However, it's useful for more than just sharing files with other people. Each time you check a file in, CVS remembers the differences between that version and the one that came before it. At a later time, you may want to go back to a previous version (perhaps several revisions ago), and CVS provides a very simple way to do that. So, it's really a pretty easy system for keeping track of all the changes you made since you start working on the project. Think of it as a safety net.

Below are some steps necessary to start using the CVS system in the Roth Lab.

How to become a CVS user.

 

  1. You must be a member of the cvs group, to have access to the central CVS repository. At the command line, type 'groups'. If you don't see 'cvs' there, you're not in the group. Ask the system administrator to add you to this group.
  2. You need to make sure that the cvs executable is in your path. At the command-line prompt, type 'which cvs'. It should come back with '/usr/local/bin/cvs', or something similar. If it gives you an error message, then the cvs executable is not in your path, and you may need to modify it.
  3. You need to tell CVS where to find the central repository, which you do by setting the environment variable $CVSROOT. It should be '/usr/local/cvsroot'. It's advisable to set in your .profile or .bashrc or other script that's run when your shell starts up.
  4. That's it! Now you're ready to start checking things out.
  5. Most people find it's a good idea to keep all the files under CVS control together, so they create a 'cvs' directory in their home, and check out all the CVS there.
  6. But wait! There's more.
    1. Talk to the owner of the project before you start checking changes back in. After all, this is CVS, not ESP. There's no substitute for talking to each other.
    2. Read the manual. There's a printed copy available (ask Frank), and it's always available online at http://www.cvshome.org/docs . It's a complicated piece of software, nobody knows all the answers.
    3. You'll notice that CVS creates a sub-directory called 'CVS', containing a few extra files, and there's one in each directory of each project. These are used by CVS to keep things organized. Except in the direst emergency, it is unwise to edit these files.

How to create a new CVS project.

(Note, this does not discuss how to set up the CVS repository in the first place. This should only need to be done once in the life of a computer system, and it's already been taken care of. See the CVS manual for details.)

 

  1. First, you need to read 'How to become a CVS user.' Only if that works can you start thinking about starting new projects.
  2. Projects are started by using the 'import' command. You can't start an empty project. The idea is that you already have a collection of files (or even just a single one) that you would like to put under CVS control. It doesn't have to work properly (if it's code), and it doesn't matter who wrote it (you or someone else). To CVS it's just a bunch of files (they can be perl files, Word documents, html, whatever). The project can consist of sub-directories, nested arbitrarily deeply.
  3. To start the new project (assume it's located in the directory 'wdir'), issue the following command:

cd wdir

cvs import –m “Imported sources” GOFish GOFish start

 

The '-m' specifies a message to associate with the very first version you check in (the version number will be 1.1.1.1 – I don't know why). You could put something different, but “Imported sources” seems good enough.

The first 'GOFish' above specifies the name of the directory under which all the files will appear; that is, when someone checks it out, they will say 'cvs checkout GOFish', and CVS will create, in their current working directory, a sub-directory called GOFish containing all the files associated with that project.

The second GOFish is what CVS calls a 'vendor tag'. The word 'start' is a 'release tag'. Both of these are pretty redundant – I've never had a use for them.

  1. Think carefully about how you will name the project, since it is difficult to change project names once they have been set up. It's not a good idea to put your name in there. It's probably also not a good idea to include things like 'perl', 'java', 'html' in the name of a project either. The name should be an abstract representation of the project's function, not a description of the implementation. Talk to somebody who's done this before, to learn from their experience. Right now (09/2001), we've decided that we'll just organize things under scientific project names, so for example, all the files related to the GOFish project will be checked in as cvs/GOFish, ditto for ClusterJudge, etc.
  2. Once you're done importing it, don't forget to check it back out. Until you've done so, all you've told CVS is that there's a new project, but you haven't given it a chance to realize that this directory from which you just checked it in is a working copy of that project. (Confusing, but true.) Checking it out (and you can check it out either 'on top of' the existing version, or somewhere else) gives CVS a chance to create those little auxiliary files that help it stay organized.
  3. You're done. Any other CVS user is now free to check out your project. By default, no permissions are set (i.e., the 'access list' is empty), but it is possible to turn on a permission system, so that the project's owner can control access to the project, in a manner very similar to the UNIX filesystem privileges: users may have any combination of read (allowed to check out), write (allowed to check in) or create (allowed to create new files) permissions.
  4. There's lots more to learn – RTFM!

 

 

This document likely contains errors and oversights. It can be improved by emailing its author.