Sean's CVS primer

people keep asking me about CVS, like what it is and how to use it, so i've finally decided to put a little something together. this page isn't anything close to extensive, but it should be everything you need to get going with cvs. further documentation can be found on the CVS home page, as well as cvs's man page (man cvs on any unix-type OS).

questions, comments, additions, corrections, et c. can be sent to finney at

So what's the big deal?

CVS (Concurrent Versions System) is a really cool tool that lets multiple people work on a single project concurrently, without stepping on eachother's toes. it provides a way to keep a history of the files that you've edited, so that if you make a fatal mistake you could back it out and recover a previous version, and it allows multiple people to work with their own copies of the source, but still providing a way to keep everyone else's copies up to date when it's decided to commit changes. personally, i use CVS for every project and assignment i work on, and its saved me hours and hours of head banging and head scratching. it's also made it infinitely easier to work with a partner or in groups.

back to top

Stuff you'll need to do first

first, let's cover all of the initial things that you'll need to do to get going with CVS for your project. if you already have yourself a repository, you can skip this first step. if you don't know what that means, read on :)

back to top

Setting up a CVS repository

if you're the one starting the CVS based project, you'll first need to set up a repository. the repository is where all the information CVS uses to keep track of your projects will go. this is what i recommend for folks who aren't familiar with CVS:

cvs -d /home/username/CVS init

back to top

Importing a project into CVS

now that you have a repository setup, we're ready to import the project. to do this, first put all of your source into a single directory. if you're an organizing freak, you can have subdirectories with more source, since importing will by default recursively go through those too. after you've done this, you can import your source like so:

cvs -d /home/username/CVS import projectname username start

can be anything you want, and it can even have subdirectories (for example if this is for lab1 of a cs63 class you could do cs63/lab1).
is the name of the "vendor" starting the repository (it can be anything, but i just use my username)
is an initial tag to be associated with the import (let's not be concerned with that for the time being, and just say "start")

now that your source is imported, you'll need to check it out. you'll need to move your old source out of the way (i wouldn't delete it until you're sure you got things working though), and then check out the project. note: you'll want to run this command from within the project directory, as cvs import works relative to the working directory (thanks to nori for suggesting this clarification).

back to top

Checking out a CVS project

this is the easy part:

cvs -d /home/username/CVS checkout projectname

there's a whole lot more you can do with this command (like checking out the project as it was at a certain date, or matching a certain tag), but for a simple intro, this is all that you need to get going. Also, if you've made it this far, you can now safely delete the original source that you've moved out of the way.

back to top

Commands you can do in a CVS project

these are commands that you can issue inside a checked out CVS project. note that you should no longer have to specify things with that -d flag, since CVS will be kind enough to remember that for you.

back to top

Getting the most up-to-date copy

since you're working on this project with possibly a number of other individuals, you might want to make sure you have the most up-to-date version of your project before you begin to make changes. you can do this by:

cvs update

note: if there are new subdirectories added to the project you'll need to add a "-d" onto the end of that command to get the new directories

back to top

Commiting changes to a CVS project

the way CVS works, the changes you make to the project are not directly put back into the project until you specifically say so. you can do this by:

cvs commit filename
(to commit a single file), or
cvs commit
(to commit all the changes)

after you issue this command, your favorite editor will pop up and prompt you to enter a log message. you can say anything you want here, or nothing at all, but you'll thank yourself later if you give a pretty good description of the changes that you've made. also, doing a single commit for each change (as opposed to one massive commit for all changes) may also make your life a little easier if you ever have to back out change or two.

back to top

Adding more files to a CVS project

as your project grows, you'll probably find yourself creating more and more files as you break down tasks into separate components. you can add files or directories to an already existing project like so:

cvs add filename

back to top

Removing files from a CVS project

there might come a time when you decide you really don't need a few files in your project. you can tell CVS to remove them from your project, and CVS will keep copies of them in its "Attic", in case you ever change your mind.

cvs remove filename

back to top

Examining changes you've made

sometimes you might want to double check all the changes you've made to a file before committing it. you can do this with:

cvs diff filename

and i actually prefer

cvs diff -u filename

there's actually a whole lot more you can do with this command (like looking at the changes between two specific versions of the file, or changes done before/after a certain date), but i leave you to the man page for that.

back to top

Examining the log of a file

when you make a commit to a project, you enter a small amount of text into a log. you can view the entries of this log with the following:

cvs log filename

back to top

Advanced CVS Tricks

Mailing CVS repository changes

if you're working on a project using cvs with multiple people, communication between all parties is essential. sure, the cvs commit log messages can be helpful, but not if people have to go out of their way to read them. so, here's is a not-too-complicated trick you can do to have all cvs commits for a particular repository mailed to someone/a list, which makes for greater transparency and better communication in the development process.

first, you'll want to check out your cvs administrative directory from your cvs repository:

cvs -d /home/username/CVS co CVSROOT

next, you'll want to edit the file loginfo. i find something like this works for me:

DEFAULT (echo %{sVv}; cat) | mail -s 'CVS repository commit'

note that DEFAULT can also be a regular expression to match against the files being committed, so you could have seperate commands for different projects. DEFAULT is just a cvs special word that catches anything not matching a previous regular expression