Using CVS for revision control

[trs80]

Intro

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 test_junk.pl 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.

CVSROOT=/home/trs80/cvsroot
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:
  /cvs_stuff/myreally/cool/directory/cvsroot

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:
/home/trs80/cvsroot
and the Working Directory will be:
 /home/trs80/working_directory

(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:
/var/www/html/cgi-bin/masterpiece

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.

Links

[0] http://www.cvshome.org - CVS home page
[1] http://www.google.com/search?hl=en&amp;ie=UTF-8&amp;oe=UTF-8&amp;q=revision+control
    - Revision control links on Google
[2] http://www.rpmfind.net/linux/rpm2html/search.php?query=CVS
    - Query at rpmfind.net for CVS rpms
[3] http://www.cvshome.org/docs/manual/cvs.html  (CVS Manual)
[4] http://www.twobarleycorns.net/tkcvs.html  (TkCVS project)
[5] http://www.cs.utah.edu/dept/old/texinfo/cvs/pcl-cvs_toc.html (pcl-cvs for Emacs - comes with some distros of Linux)
[6] http://www.gnu.org/software/emacs/emacs.html (Emacs)
[7] http://www.codeforge.com (CodeForge)
[8] http://subversion.tigris.org/ (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

[atcroft]

Excellent posting, trs80, and certainly (after one has gotten used to using it) not only a convenience if the project may be spread across multiple developers at some point, but a life-saver when those inadvertant accidents occur. (Or am I the only one who has been bone-headed/fumble-fingered/otherwise unlucky enough to lose entire programs before?)

My only addition would be to mention the book Open Source Development with CVS, by Karl Fogel and Moshe Bar, which seems to be a very excellent resource to add to your list. Portions of it are available online under the GPL at http://cvsbook.red-bean.com/. (I'm only a few chapters into the tree-ware version myself, although I have noticed that that version seems a little more difficult to find recently.)

[Abigail-II]

Just a few things.

You are claiming CVS is the most widely installed and used revision control system in the GNU world. This may be true, but do you have anything to back up your claim?

There isn't a need to add a CVSROOT to your environment variables permanently. It's only need if you either initially checkin a source tree (using "cvs import"), create a repository ("cvs init") or do the first checkout of a project ("cvs checkout"). But for normal day to day actions ("cvs add", "cvs commit", etc), the repository is retrieved from the CVS admin files.

You also say a file cannot be removed from CVS, but I thought that's what "cvs remove" is for.

There is one action that's lacking in the CVS command set. You cannot rename a file other than manually modifying the repository and the admin files. This is troublesome if many developers have checked out the module.

Abigail

[Tomte]

There is one action that's lacking in the CVS command set. You cannot rename a file other than manually modifying the repository and the admin files. This is troublesome if many developers have checked out the module.

You're right, there is no way of renaming a file while keeping track of this change in cvs, but instead of manually messing around with the administration files, you (AFAIK) would (in your working dir):

• $> mv myfile ~/backups
• $> cvs remove myfile
• $> cvs commit myfile
• $> mv ~/backups/myfile newname
• $> cvs add newname
• $> cvs commit newname

This is one of the few ugly parts of CVS; but while your starting to use it, you may give meta-cvs a try. I did not, because of my high workload there's no time for such improvements :-(, but it seems to be worth a try.

regards,
tomte

[Abigail-II]

That will make it impossible to retrieve older versions of the file, and your CVS log will be erased.

That's why I prefer to modify the admin files by hand.

Abigail

[Rex(Wrecks)]

Just a link and a note to a GUI and CLI client for CVS repositories.
CVSGui
They also have diff tools, and other CVS GUI tools.
They have tools for many platforms including Windows. Heck, they even have Mac tools!

Note: I front-paged this because I see many people who are primarily small scripters and small project people that NEVER use source repositories and don't know the value they have.

"Nothing is sure but death and taxes" I say combine the two and its death to all taxes!

[Chmrr]

There is one additional point to bring up concerning Perl and CVS; the actual versioning itself. Perl's $VERSION variable assumes that version 5.101 is just a small update on 5.1 -- CVS believes that they are 100 revisions apart! Things get even more confusing when Perl claims that 5.2 is more recent than 5.101 This can lead to Wacky Hijinks^(tm) if you set the $VERSION variable in your program based directly on CVS' $Revision$ tag. You have been warned.

perl -pe '"I lo*`+$^X$\"$]!$/"=~m%(.*)%s;$_=$1;y^`+*^e v^#$&V"+@( NO CARRIER'

[Joost]

I usually do something like

$VERSION = sprintf "%d.%03d",q$Revision: 1.15 $ =~ /(\d+)\.(\d+)/;

That will give a $VERSION = '1.015' for $Revision 1.15

-- 
Joost       downtime n. The period during which a system
            is error-free and immune from user input.

[Tardis]

To do your cvs 'stuff' from within emacs, there is really only one key combination you need to remember:

CTRL+X, V, V

This will popup a buffer for you to type your change comment into, and prompt you to press CTRL+C, CTRL+C when finished.

This makes it almost as easy to commit as it is to save, so you can get into the habit 'Commit early, commit often' :-)

[hding]

I've used pcl-cvs a little bit with xemacs, and it seems to work perfectly well. For doing relatively simple things like I do, it's just as well to use the command line directly, though.

[blahblahblah]

Thanks for taking the time to write this up! I've always meant to get around to learning cvs, and your clear introduction made it hard to procrastinate any longer. After getting my feet wet with the windows command line version, I've now moved on and have CvsNT and wincvs working together. I'm just about ready to make the switch from the somewhat outdated system I'm currently using, except for one thing that I can't figure out how to do in cvs.

Our current system is an old thing that someone who doesn't work here anymore wrote. One difference between it and cvs is that it doesn't allow you to 'commit' a single file at a time - you have to commit everything that you've changed in the module. So if I've changed two files, a.pl and b.pl, in my directory and I want to commit a.pl, I have to also commit b.pl. The system maintains separate version numbers and logs for the individual files and for the whole module. Sometimes this can be a little bit of a pain when I've finished working on a.pl and have some incomplete changes in b.pl, but for the most part it's very useful. It allows us to make related changes in different files and then keep track of them as a set. This is useful for example when I need to undo or fix a previous change to a file, I can see what other files were included in the same commit and check whether they have the same problem.

Is there anything like this in cvs, where the module/repository has its own log and version numbers? Is this what tags are for? I see that Subversion claims it's better than cvs because "directories are versioned." Is this what they mean?

I hope asking this cvs question isn't too off-topic -- I didn't know where else to ask. Strangely, searching google groups didn't show any cvs-related discussion groups. And going by the archives, the mailing lists on cvshome looked pretty inactive.

[Jenda]

I looked at a few version control systems for Windows and the one I liked best is CS-RCS (free for single user with local repository, based on GNU RCS). It's a shame that our company already bought PVCS and wants us to use it :-(((

Jenda

[Anonymous Monk]

Better late than never...

O'Reilly have announced "Essential CVS" and have made chapter 2, which is a CVS quickstart guide, freely available.
It's a good introduction and worth a read if you're new to CVS.

http://www.oreilly.com/catalog/cvs/

[spookyj]

I was looking at the manual for CVS at the GNU website and even at the actual CVS website. Their manuals (even though extremely informative) are convoluted. I really only needed to know how to use CVS for small projects and programs for one programmer on one computer (me). This is an excellent topic. Great stuff! Kudos!

[Vautrin]

I'd just like to add that if you use Emacs there are built in CVS controls. It makes it a lot easier to work in your source tree, and then just hit C-x v i to register a file when you create one, Check out:

http://www.emacswiki.org/cgi-bin/wiki/PclCvsTips
http://www.emacswiki.org/cgi-bin/wiki/PclCvsTips

[Poetic Justice]

I've read a lot of useful posts on Perlmonks, but this one is the most helpful for me to date. I've use revision control at work for years, you convinced me to install CVS, and build my own repository. I guess I've forgotten how hard I had to work to build all of my personal source code over the years, and all I've ever done is copy it to CD, diskette, or external HD. Thanks for the post, and the motivation.