flipcode - CVS Quick Start Guide

CVS Quick Start Guide
by (26 November 2002)

What Is CVS, and Why Would I Bother?

CVS is Concurrent Version System. Primarily CVS was developed for the unix environment, but both client and server applications are now available for the Windows platform too so it's readily available to all of you out there.

Now. What is it? I'll tell you. It's a nice way to keep backups and versions of your code (and even binaries could be stored) at a server. Thus it's also possible for others to join your projects without the need to manually keep track of versions and who has the latest version or release build.

Perhaps you have heard about Source Safe (from Microsoft Corporation), Perforce (from Perforce Software Inc) or similar. CVS is all that, but it's 100% free for unlimited users, files and time. This is not to say that the others are bad or should be excluded just because they cost money, but CVS offers home users a way to get a cheap and fairly easy-to-use backup/sharing system.

Now why am I writing a tutorial about it then there are so many out there? Well, first of all, I don't think you need all of the fancy features offered to start, and they will just confuse you in the beginning, since the world of CVS is quite big. It's easier to focus on the main functionality first! I'm also asked about CVS and how to use it fairly often, so this will be a nice reference for me to point at too, of course.

Add that the CVS manuals out there describe everything in a detailed manner (which could be a good thing), but I don't think you will need that right now. It's better not to scare you away, and if you want to find out more later, you could always look it up in one of these CVS manuals (Cederqvist is a good resource).

The Server

You can find a linux server at www.cvshome.org. A windows server can be found at www.cvsnt.org.

Both of these sites have good explanations on how to install them. I have only installed the NT server myself and it wasn't so hard.

To start with, it would be easiest for you to try to get CVS access from somebody already running a server, because when you don't know what you can do with CVS, it's not the easiest task to set up a server :-/

Getting Started

You now have a server set up with some usernames and passwords, so the first thing you will need to do is to set up the CVSROOT environment variable by typing (in windows command line):

set cvsroot=:pserver:username@some.server.com:/test

Where username is (doh) your username, some.server.com is your DNS name or IP number of your installed CVS server. /test is the name of the so-called repository which is set up on the server. This is used to make it possible to run more than one group of users (or even down to project level if that's appropiate) on one CVS server.

After that, to log in we use the command:

cvs login

Where I log in as the username specified by CVSROOT environment variable. Then a prompt for the password will be shown, and you of course enter your password specified on the server. The server should then tell you that you are logged in. If not, something is not set up right with your install and you will need to debug what's wrong.

The server has a specific directory where all the projects (including all sources) are stored. As a client user, we don't need to think about this at all since it is handled by the server.

Creating A Module

A module is a project within the repository. In our group, we use one module for each project since having all projects under the same roof can get dirty after a while. It's easier to maintain smaller modules. At least we think so, you form your own opinion on this by experience but as a start, we'll just try to create a simple module and work from that.

Creating an empty module is a little bit tricky, but the import command will help us with this. I will assume that you have created a local directory on your computer where you want to keep your modules, somepath/repositoryname is a pretty good start I think, and that you are located in this directory. Let's have a look at the commands for creeating a "myproject" module:

md myproject
cd myproject
cvs import -m "Creating my first project" myproject thec start
rd myproject

The cvs import command works like this.

The -m and following "" sentance is just a log message, storing what you want to write there. Just type whatever really. CVS likes to have one so just do it :-)

The next argument, myproject is the name of the module, the same name as the folder will work fine.

thec is the vendor tag. I just type my own handle there so people can see it's me who started the project, but it's really nothing to care about, the same as the last parameter; the so called release tag. If you want to get the first version of the repository (if you add files to your myproject-directory before executing the command, they will be added) you can use this, but we'll leave this for now.

Now we have a fresh module to work with!

Check It Out Now, Funk Soul Brother!

Since we want our local copy to keep in contact with CVS, CVS stores CVS folders (damn, how many times will I need to type CVS ;-) in all of your project directories. However, after the import no CVS folder is created and thus we deleted it to check it out again. Run this in your local repository path:

cvs checkout myproject

Not too much to think about there, myproject is our project and we're checking it out, but if you take a closer look at what happend you will see that a myproject folder has been created and inside it there is a CVS folder which will keep track of our versions locally, and merge our source files with the versions on the server. It's pure magic ladies and gentlemen, but luckily, we don't need to know how the server handles the versions (puh).

Updating The Project

Before each commit (explained later) and before you start writing your code for the day, the best thing is to check out the newest version of the files, so that you're using the latest available version. Note that this does NOT upload any of your code to the server so if you have made some bugs since last night, don't worry, noone will see since you have control over uploading source! :-)

cvs update -d -P
cvs up -d -P

The second line does exactly the same as the first, it's just shorter to type. -d option tells the client we want to search all subdirectories for updates and -P specifies we do not want to download empty folders. Believe me, just learn to do it this way and you will never wonder why you can't remove folders within the CVS server ;-)

Adding A File (or Two)

Adding a file is easy as one two three, just create the files within the myproject directory and we can continue. Let's say you've created "test1.h", "test1.cpp", "test2.h" and so forth, we can then add a file with one or some of the following lines:

cvs add test1.h
cvs add test2.h test2.cpp test3.h
cvs add .h .cpp

As you see, you can use wildcards and specify many files on one line. Note, this does not actually upload the files to the server, let me just add one more method to add files and we're all set for uploading.

cvs add -kb mypicture.jpg

For natural reasons, it's hard to maintain binary files within the CVS server as normal text files, so we use the -kb switch to make sure it's treated as binary all the way. This means that if you make a change to the picture, the WHOLE picture will be uploaded the next commit, and not just a part of it as the source code would.

CVS Commit

Before making a commit, please make sure you have run cvs update -d -P since it makes it less possible that you screw things up literally. By just typing:

cvs commit

All files you have changed (you will see a 'M' or a 'P' before the filename when doing a cvs update) and added will be uploaded to the server, and the others will get them next time they use cvs update. Easy? Should be.

Removing Files From The Server

If you want to remove files from the server, the first thing you have to do is to remove the file on your local drive:

del test1.h
cvs remove test1.h
cvs commit

Of course you run update before you start deleting files. The next time the others run their update, the file will be erased on their side too.

Closing It Up

This was the very basics of CVS. If you want to read more, I recommend browsing www.cvshome.org for more resources. But I just wanted to show you how easy it could be to really get to start using a version control system, which is really a good direction in your development since it instantly makes it easier to backup, share and overwiew. You are now forced to think before you set up a directory structure for your projects, and that can't be bad :-)

If you think this tutorial helped you, I would love to hear a word from you so please just drop a line to thec@home.se with comments. If you think it sucked or CVS sucks, I can't help you ;-)

Albert "thec" Sandberg
Coder of Outbreak

Proofreading by Def Base of 32Bits.co.uk