CMSC 491/691: Graphics for Games

Using CVS to submit assignments

Overview

CVS is a popular free revision control system. It is designed to allow one or more people to work on the same project, keeping checked in versions of files in a common repository. Its main use is for managing source code in projects with multiple developers, and it includes some pretty nifty support for merging independent changes to text files. In fact, using some sort of revision control is almost required for any reasonably complex software project. The revision tracking features are pretty handy even when working alone. You can go back to any revision of your files that was ever checked into the repository, either by revision number or date. I use it for the revision tracking features for all of my web pages, lectures, exams, papers, ....

In our case, you will be checking in your assignment files, and the TA and I will be checking them out to grade.

CVS client

To use it, you will need a CVS client, a program that runs on your system and talks to the repository. Which client you use, and whether it is already installed, depends on your system. There's a command line client called "cvs" on the GL linux systems. If you have your own Linux system, it may already be installed as one of the base packages. If not, you should be able to install it with your normal package installer (e.g. apt-get). On the Mac, a command-line cvs client used to be pre-installed, but if you have a more recent version of MacOS, you may need to install it yourself. I use the "homebrew" package installer, though it is available with "MacPorts" as well, or not that hard to build and install from source. On Windows, I recommend the TortoiseCVS client.

Initial checkout

First, you must check out your directories from the repository. This will give you your own working copy of the files. Do not attempt to work directly in the repository, CVS will get quite confused if you do this, and we probably won't be able to check out your code to grade it! The initial checkout is the only time you need to tell it where the repository is. After the intial checkout, CVS can figure out which repository to use. All of the major CVS commands apply to the current directory and all directories under it.

On the GL systems, you'd use a command like this (replacing the username and directory)

cvs -d /afs/umbc.edu/users/o/l/olano/pub/491 checkout -d directory_name_of_your_choice your_umbc_username

Since we are creating graphics applications, you will probably actually want to develop on a remote system instead of on GL. You can still do that, with a slightly different repository name. With a remote command-line CVS (e.g. linux or mac), you'd use a command that looks more like this

cvs -d username@gl.umbc.edu:/afs/umbc.edu/users/o/l/olano/pub/491 checkout -d cs491work username

On Windows with TortoiseCVS client, you'll get a dialog to set up the server. Fill in the Protocol as "Secure Shell :ssh:", the server as "gl.umbc.edu", the path as the long "/afs/.../491", and your username under "User Name" and "Module".

Editing

Edit away... No need to do anything special

Adding, removing, and ignoring files

If you add files, you ***MUST*** let CVS know so they'll be checked in. With TortoiseCVS, all of these commands are available by right-clicking on the file. With a command line CVS, you would tell CVS that you want to add a file with:

cvs add file

To tell CVS you're removing a file (so it won't come back next time you update — see below):

cvs remove -f file

To tell CVS to ignore a file (executable or image file you generate, for example), add it to the list in the .cvsignore file in that directory. I've added a bunch of initial files to ignore to the .cvsignore file for you, but you are free to add more.

None of these commands immediately add or remove the file from your repository. They just tell CVS that you want to do so on your next commit.

Checkpointing and submitting your changes

Your changed or added files are not copied to the repository until you check them in. You must do this for us to be able to check out and grade your work, but you can do it as many times as you want before then. First do this:

cvs update

This will syncronize your local copy with any changes someone else might have checked into the repository already (in multi-person projects), and list a status code for each file that might need further attention. Files CVS doesn't know about will be listed with a '?'. Next, tell CVS to add or ignore each of them, then try the update again. You should see "A" for files being added, "M" for files that have been modified, and "R" for files to be removed. If you see an "C" files, those may have been modified in your local copy AND on the repository (you won't ever see this if you are working alone in a single directory). If you do, you may need to edit and fix them. Areas where CVS can't figure out what to do will be marked in the file with <<<<< and >>>>>.

It's good practice to make sure CVS knows about (or knows to ignore) every file before you commit any check in.

Now check them into the repository:

cvs commit -m "short message about this checkin"	

Now check to make sure it worked:

cvs update

This time, it shouldn't list any files. If it does, something went wrong. Make sure you've told CVS to add or ignore if necessary, and try again, or ask for help.

Your submission is whatever you have checked in at the time of the deadline.

Getting updates and previous revisions

In normal use for group projects, you would often need to get changes checked in by someone else. In class, you will still need to do this to get your grades, if I make any changes to the initial sample files, or add files the later assignments. You can get these by using the -d flag for cvs update to get any new directories:

cvs update -d

You can compare your current version to any previously checked in version with

cvs diff -D date file

You can also get a whole new copy of your checked in files from any past date by adding the -D flag to your checkout command, though this can leave your repository "stuck" on the previous versions until you do a "cvs update -A", so I'll often just check out the previous date in a whole new directory just to be safe.

To just throw away your latest changes and go back to the last checked in version
cvs update -C file

To figure out which revision is which (assuming you entered reasonable log messages when you committed your changes), do

cvs log file

Learning more

List of all CVS commands

cvs help

Help on any one CVS command

cvs --help command

General CVS manuals, downloads, etc.: www.cvshome.org