CSC209: Software Tools and Systems Programming
Using CVS

Review

Master copies of files live in a central repository

Repository also records all revisions to files

One or more users have local copies of files on their machines

Users make changes to local copies at will

Users can synchronize with master copy

Copies changes from repository to local machine

Notifies users of conflicts between their changes and changes to the master copy

Users must edit files to resolve conflicts

Users can commit changes to the master copy

Writes their changes into the master copy so that other users can get them

Users can revert to an older copy of a file

Like an editor's "undo" command

Local Use

Note: this page has more information on using CVS from home.

CVS uses three environment variables:

If you are using a CDF machine, set CVSROOT to /u/csc209h/summer/pub/repo/userid, where userid is your login ID. You do not need to set CVS_RSH for local use, but you should set EDITOR to pico, vi, emacs, nedit or some other editor.

Once you have set your environment variables, you can get a clean copy of the files that are in your repository. 

cvs co assignments

(You may want to do this in a special subdirectory you have set up for working on this course.) You should now have a directory called assignments containing (at least) two sub-directories. The first is called CVS. It, and other directories with similar names, holds administrative information that helps CVS keep track of what you're doing, and what it needs to do. Never delete these files, or edit them directly.

The second directory of interest, a1, holds all the files for Assignment one. Other directories will be added as we go along.

Remote Use

If you are using CVS remotely, you must set the CVS_RSH environment variable on the remote machine (St. George students: not on the lab machines) to point to your SSH client. On Linux, this is typically /usr/bin/ssh; on Windows, I set it to ssh, and then make sure that ssh.exe is on my path.

You must then set the CVSROOT environment variable on the remote machine to:

:ext:userid@host.utoronto.ca:/u/csc209h/summer/pub/repo/userid

where userid is your login ID. The first field, "ext", tells CVS to use external password checking, i.e. to get the CDF machines to check your password. The second field (your login, and host.utoronto.ca) tells CVS who you are, and what machine your repository is on. The third field is then the full path to your repository.

The way you set an environment variable depends on which shell you are using. The default on St. George CDF machines is tcsh; if you are using it, the syntax is:

setenv CVSROOT /u/csc209h/summer/pub/repo/userid

If you are using bash, on the other hand, the syntax is:

export CVSROOT=/u/csc209h/summer/pub/repo/userid

Once your environment variables are set up, check out the course exercises as described earlier.

Key Commands

cvs checkout projectname
Copy a project from a repository to the local directory. This command should only be run once.
cvs add [-kb] [filenames...]
Add one or more files or directories to the repository. If the file(s) should be treated as binary (e.g. images), use the -kb flag.
cvs delete [-f] [filenames...]
Delete one or more files from the repository. The files must also be deleted from your local machine; you can either do this before running the command, or by using the -f flag. Note that directories cannot be deleted (which is one of CVS's big weaknesses).
cvs update [-d] [filenames...]
Update local files from the repository. If a file has changed in the repository, but has not been changed locally, the changes from the repository are copied to the local machine. If a file has been changed locally, but not in the repository, it will be marked as modified. If changes have been made in both places, CVS will signal a conflict, which must be resolved (by editing the file) before the local changes can be committed to the repository. The -d flag causes this command to work on sub-directories recursively.
cvs commit [-m message] [filenames...]
Commit local changes to the repository. This command can only be run after cvs update (which compares local files to the repository), and only after conflicts between local changes and changes in the repository have been resolved. The -m flag can be used to provide a short log message on the command line. If it isn't used, CVS will launch the user's editor to get a log message.
cvs log [filenames...]
Show the history of one or more files, including revision numbers, who made the change, and log messages.

Reverting to Old Versions

In order to get a file or files back into the state they were at a particular time (e.g. in order to mark a student's submission), you should use:

cvs update -D date
where date is the moment in the past that you want to synchronize with. From the CVS manual:
A wide variety of date formats are supported by CVS. The most standard ones are ISO8601 (from the International Standards Organization) and the Internet e-mail standard (specified in RFC822 as amended by RFC1123).

ISO8601 dates have many variants but a few examples are:

1972-09-24
1972-09-24 20:05

(There are a lot more ISO8601 date formats, and CVS accepts many of them.) In addition to the dates allowed in Internet e-mail itself, CVS also allows some of the fields to be omitted. For example:

24 Sep 1972 20:05
24 Sep

The date is interpreted as being in the local timezone, unless a specific timezone is specified.

Updating a file to a particular date, or to an old revision, sets the "sticky" tag on the file (see section 4.9 of the CVS manual). When a file's sticky tag is set, "cvs update" will not work on it. This is to prevent you from reverting to an old version of a file, then accidentally checking it in on top of someone else's more recent changes. You can get rid of sticky tags by typing:

cvs update -A

Where Else to Look

CVS Manual: http://www.cvshome.org/docs/manual/cvs.html

CDF Guide to CVS: http://www.cdf.toronto.edu/workathome/index.php3?id=39

Common Problems

Two problems with CVS have come up repeatedly during this course:

Lock Files

If CVS is complaining about lock files, it means that it thinks you have started a check-in from one machine, but have not finished it before starting a check-in from a second machine. For example, if you are checking in files from home, and your connection goes down (or you use Control-C to stop the check-in), CVS will wait for you to finish checking in from there before allowing you to check in from (for example) the CDF lab. As Section 10.5 of the CVS manual says:

If several developers try to run CVS at the same time, one may get the following message: 
    [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
CVS will try again every 30 seconds, and either continue with the operation or print the message again, if it still needs to wait. If a lock seems to stick around for an undue amount of time, find the person holding the lock and ask them about the cvs command they are running. If they aren't running a cvs command, look in the repository directory mentioned in the message and remove files which they own whose names start with #cvs.rfl, #cvs.wfl, or #cvs.lock.

Sticky Bits

If you use cvs update -D to restore files to the state they were in at a particular time, or cvs update -r to restore an old version of a file, CVS marks your local copy of that file as "sticky". This means that it will not update the file the next time you do cvs update, or let you commit it with cvs commit, since it knows you are now "behind the times". (To understand why, think about how other developers working on the same project would feel if they had updated a file three times, only to have you accidentally put it back the way it was two weeks ago.) You must use cvs update -A to remove the sticky tags before you can check in. See Section 4.9 of the CVS manual for more information.

$Id: using-cvs.html,v 1.1 2005/01/04 21:59:00 reid Exp $