The intent of this article/node is to give a short (semi-accurate) overview of the steps it takes to "start" using [0]CVS on your local machine. This is not intended to be an advanced usage, "The Only Way", or even "The Right Way" to use CVS, but instead hopes to get those that might otherwise pass it up to see that its isn't hard to keep things "under control". It is based on the perspective that you have already created some directories/files and you are wanting to use those as the basis of your project (CVS repository). I hope that others that have been using CVS longer and for more robust projects will share their comments. All feedback is welcome.

Intended Audience

Developers that have not yet taken the plunge to install and use CVS for their projects.

Why use [1]Revision Control?

Well... because you should. Just like you should brush your teeth. There are lots of reasons to or not to, but just like brushing your teeth you will likely suffer less and spend less time in painful situations if you use a revision control system.

Why CVS?

I am focusing on CVS in this guide because it is currently the most widely installed and used revision control system in the GNU world and is freely available.

The Beginners CVS Guide (for Perl Developers)

Most books on good software development stress the importance of revision of control for keeping track of what you did, when you did it, and if you are on a team, who did it.

Like a good Perl programmer I am extremely lazy and have avoided putting anything in version control for years. Now I realize that it isn't lazy its almost suicidal not to. I have been able to keep track of what I did and when I did it fairly good in my head....or so I thought (ugly details removed). So begins my journey into CVS for Perl source control.

Now that I have moved to Linux full time I am slowly applying and enjoying all the benefits that it brings. CVS is supported under OSes other then Unix, but when I last went to try it, it still suggested the server portion not be run on some platforms so I had used that as another excuse to avoid it. CVS was included on the ISO image I downloaded so it was as simple as installing the [2]RPM to get the binaries installed. I will leave the build/install process to the [3]documentation supplied with CVS if you don't/can't like/use RPMs.

I got ready to start and thought I would read the [3]documentation first for a change. I did and that didn't seem to help; they make more sense after you know what they are talking about however :) I looked up a couple of tutorial sites on the internet, even found one angled toward Perl users, which is what I used to get started, but still didn't go as far as I would have liked.

Clean up your act!

In my perpectual laziness the first time around I didn't clean out all the junk files. Not that files can't be removed from CVS, but why add them in the first place if you know they are junk.
So clear out all the old .bak and that aren't productive/useful before you even think about moving on to the next step.

Making a CVSROOT (aka Repository)

On NT/2000/XP you will need to add CVSROOT to your environment variables. I am not going to go into details on NT in this tutorial since I don't have access to a windows machine to confirm the steps. (win9x ???)

On a Unix based machine the preferred way to add CVSROOT to your environment is to make an entry in your profile. This various from shell to shell, for me and my bash shell I made this entry in the $HOME/.bash_profile file.

export CVSROOT

The CVSROOT is where the repositories will live. The repository is really ugly and there is generally no reason for you to look at it directly, consider yourself warned.

Now run this command (read below for important path information):
 cvs -d $CVSROOT init

It should return you to the command prompt with no messages if you did everything right.

Now if you have used or want to use a completely new tree you have to create all the directories up but not including the last one. So if you wanted to have a repository live in:

You could have to issue something like:
 mkdir -p /cvs_stuff/myreally/cool/directory

You COULD include the /cvsroot, but if you don't the cvs command will add it for you.

Adding your killer app to the repository (CVSROOT)

In the CVS docs at the CVS site there is a nice little getting started section that attempts to help you set things up, but if you tend to not read all the information leading up to a point (like me) and skip right to the topic of interest they gloss over some important details on how to get your present files into the repository, which is in part of what prompted me to write this.

We will deal with 2 main directories, the CVSROOT and the Working Directory. For this example the CVSROOT will be as shown above:
and the Working Directory will be:

(in the CVS docs they call it rdir (repository directory) and wdir (working directory) I preferred it spelled out for my simple mind :)

So with those "facts" established let say you have a masterpiece of Perl code in some obscure corner of your machine such as:

We want to move that into CVS so we can keep better tabs on it and make it available to others as the need should arise. There a minimum of three variables now that are important to creating the repository, but once it is created only one of them is important.

Repository_Name - this one remains important since it is what will be "checkout"ed of CVS. The repository name is completely at your discretion, no magic* is performed on it based on path or environment variables. It does however allow you to specify the path under the CVSROOT. If you say "YourName/KillerApp" as the Repository_Name then it will always need to be "checkout"ed (see below) with the full sub path (YourName/KillerApp). I say this because the first time I created a repository I thought there WAS magic and stopped one directory short of the files I wanted and got 10 directories and a load of files that had nothing to do with what I wanted in CVS, so yes there really are people out there that stupid :)

Vendortag - I honestly don't know enough to explain when this is useful so for the purpose of this discussion simply set it to your personal ID or "code name" (for me trs80).

Releasetag - This is the version tag in a way, but is string not numerical nature so if you are working on Masterpiece-01 you could use that as the releasetag. In the CVS docs the initial import is done with a 'start' string for the releasetag value. That is most likely a safe way to begin using CVS and as your knowledge/needs grow you will be able to better decide how to name it.

  1. cd /var/www/html/cgi-bin/masterpiece
  2. cvs import -m "Import of Killer App" Repository_Name Vendortag Releasetag

    (aka cvs import -m "Import of Killer App" KillerApp trs80 start)
    You should see a list of the files as they are added to the repository with a letter in front of each one indicating the success code of the addition. If it is a fresh directory it is unlikely you will see any thing "odd" unless you have files of "unknown" content that CVS is not capable of checking revisions on.

The files in the directory you are currently in will NOT be effected, the 'cvs import' command will simply copy each file and log it into the repository. That being said, aways backup before doing anything "new".

The -m is a common option on the cvs sub commands that allow you to enter comments for the "Change Log". If you omit the -m cvs will open the editor (as assigned by your environment as the default) to allow you to enter comments as well so you can't say nobody reminded you to comment on what the heck you were doing at 3:00AM.

"Checkout" the files into your working directory

Once the files are in the repository you will need to check them out of CVS into your working directory so you are sure you are working on the right code and "Its the Right Thing to Do"TM

Checking out is done by issuing the following commands:

cd /home/trs80/working_directory
cvs checkout Repository_Name
(aka cvs checkout KillerApp)

That should have given you a list of all the files and directories brought out of the repository.

"Commit" a file

Go ahead and make a change to one of the files so we can "commit" a changed file.

Once you have edited one run this command:
cvs commit <filename>

If you use the above command you will be presented with an editor asking you to make a comment for the change log. You can avoid the editor by using:
cvs commit -m "Change Log Message" <filename>

Final Thoughts

That covers the very basics of CVS. There are about 1,784 other things you MAY need to know about CVS, but at this point you can create a repository, add files to the repository, check them out, and commit changes. When working in a group environment CVS brings forth some powerful tools to allow for more then one person to work on a file at a time and not lose any changes or at least minimize the number of them, depending on how well separated your efforts are.

I have only found one good standalone GUI tool so far in my quest for handy tools and that is the [4]TkCVS application. It works well and gives good access to most of the commands via icons (commit, checkout, branch, etc.) and lesser used commands via the tool bar.

There is a [5]pcl-cvs project for Emacs that I looked at and appears to offer everything (just like Emacs), but since I don't use [6]Emacs I can't comment on its usability.

[7]CodeForge offers CVS integration with its editor and supports CVS.

There is an up and coming Revision Control system that is designed to replace CVS called [8]Subversion, which is due to be at beta stage in Q4 2002.


[0] - CVS home page
    - Revision control links on Google
    - Query at for CVS rpms
[3]  (CVS Manual)
[4]  (TkCVS project)
[5] (pcl-cvs for Emacs - comes with some distros of Linux)
[6] (Emacs)
[7] (CodeForge)
[8] (SubVersion)
* well if you consider it using the environment variable CVSROOT to know where to put the files, then I guess there is some magic

Updates: Minor verbiage and grammatical errors were corrected (thanks duelafn,premchai21 ) and the Links were turned into real links at the urging of podmaster