CVS Starter Guide: Basic Ideas

I think it'll be easier to understand how to use CVS, if I explain some of the concepts and terminology.

There are actually many version control programs out there. The one we're using for Narnia's MUF programs is called CVS1. I chose CVS over other systems because it lends itself well to large collections of single-file programs--the very situation we have with Narnia's MUF program collection.

Repository
A term you will see frequently in discussions about CVS (or any other version control system) is repository. Programmers will say things like "I just committed my changes to the repository." The repository is where all the files that are being 'version controlled' by CVS is stored. Not just their current versions, but all their past versions as well. If say, "Animazing" has been edited and committed 313 times, CVS will have stored in the repository 313 versions of its file. The repository lives on a server so that we can access it over the network. Currently, Narnia's CVS server lives on the same machine as the muck: muck.narniamuck.org.

CVS Client
A CVS client is simply a program that handles the work of communicating with the CVS server for you. Whenever you checkout, add, commit, update, files in the CVS repository, you do so using a CVS client. There are several options out there. For myself I use the command line client because of where I do my programming work. When I need a CVS client for Windows I use TortoiseCVS or perhaps SmartCVS. Mac/OSX users can either use the command line tools or SmartCVS.

checkout
When a programmer needs to edit a given file, or multiple files in a project, he "checks them out" of the repository. What this really does is copy the files onto the programmer's computer so he can edit them. Whatever changes he makes to the "checked out" copies aren't put back in the repository until he 'commits'. This allows the programmer to edit a program, check that his changes work, that the program compiles without error, etc. before saving the changes (committing) to the repository.

commit
By now, this one may be obvious. Whenever a programmer has changed a program and he/she is satisfied that the changes are correct, he saves the changes to the repository. This is called "committing". So programmers will say things like "Yeah, I committed those changes today."

update
If you have a file already checked out from the repository, you'll need to make sure you have the latest version before editing it. This is called an 'update'. You should always do an update before starting a series of changes to a file. You never know whether or not another developer might have made changes to a given file in the course of working on a different request.

add
If a file (or in Narnia's case, a program) isn't in the repository, it will need to be added. Be aware that the 'add' command doesn't 'commit' the change. So you have to perform an add for the file and then perform a 'commit' to finalize the addition to the repository. If you're starting a new file/program, it should be added to the repository early, possibly as an empty file!

diff
An all important tool that becomes even better with version control. diff displays differences between two files. CVS's diff will perform the same comparison between versions of a file. This way if you wonder what I changed to fix request #45533, you can use cvs diff to check the fixed version against the prior version and see the changes. Some CVS clients provide a fancier version of this command, with color highlighting and the like. Look for words like 'compare' or 'diff' or...

Log Entries
When committing a change, the CVS client will prompt you for a log entry (or you can specify one on the command line). The log entry is stored in the repository for future reference. It is important to give a simple explanation of what prompted the change. With Narnia, you should include the issue/request number, complete with a # sign. I tend to do something like: Issue #345. Fixed typo in the 'you are full!' message. Generally one sentence or so is sufficient, especially if there's a request # included.

The file itself should have a section that looks like this:

(
$Log$
)

Or:

(
$Log: heartbeat-mobiles.muf,v $
...


With $Log$ or $Log: ...$ in the file, your log entry will be automatically added to the file. That way it will be there for the next person to read easily, right there in the file.

• 1. It stands for Concurrent Version System, but hardly anyone uses the full name--typically it only comes up in this sort of document.