Harness the Power of CVS for Your Site

SitePoint Members Hit Sourceforge

This story is 100% true and the names have not been changed to protect the guilty!

Once upon a time, a PHP coder known in some circles as HarryF decided to write a PHP application (the name of which will be made available in some far-flung future when it's finally finished!). While he was frantically coding his creation, another coder and Master of Photoshop, known to some as Glenplake, kindly offered to help HarryF design the user interface for his application.

So the two began to collaborate with much enthusiasm, but it soon became apparent that all was not well. HarryF's weekly ZIP files containing his latest work were getting confused with Glenplake's updates, and a great distance over land and sea separated the two, which only added to the chaos. Hair loss ensued.

Luckily, in the Sacred Mountains of Open Source there stood the Temple of Sourceforge, from which all good things do issue. Following the The Ritual of Registering for a New Project, our two hardy PHP coders where able to gain access to the Fountain of CVS and thereby finally collaborate successfully. Things got back on track, the project steamed ahead, and the coders kept what remained of their hair.

Sourceforge requires us developers to access it using the ssh method. If you run Windows, it's worth setting up some environment variables to make life easier, so before we go any further:

1. Download ssh from: http://download.sourceforge.net/sfsetup/. The file will be named something like ssh-1.2.14-win32bin.zip
2. Unzip to a directory: C:\program files\ssh
3. Now open an MS DOS prompt and type the following to create the directory c:\program files\ssh\.ssh (Windows Explorer won't let you make directories beginning with a full-stop (or period)):

cd \progra~1\ssh  
mkdir .ssh
4. Update your system Environment Variables:


• Right-Click "My Computer" and select "Properties"
• Click the "Advanced" tab
• Click "Environmental Variables"
5. Update "path" variable (used to run programs from anywhere on your system) with the ssh installation directory
• Select the "path" variable (under system variables) with your mouse and click "Edit"
• At the end of the box you're now editing, add "c:\progra~1\ssh" with a semi colon before it i.e. ";c:\progra~1\ssh"
6. Make your HOME variable, which is required by CVS to find the ssh application
• Click "New System Variable"
• Name the new variable "HOME"
• Set the variable value to: "C:\progra~1\ssh"
• Click "OK"
7. Make the CVS_RSH variable to tell CVS what authentication method will be used
• Click "New System Variable"
• Name the new variable "CVS_RSH"
• Set the variable value to: SSH
• Click "OK"
8. Make the CVSROOT variable which tells the CVS client which CVS tree to use
• Click "New System Variable"
• Name the new variable "CVSROOT"
• Set the variable value to: ":ext:loginname@cvs.yourproject.sourceforge.net:/cvsroot/yourproject"
• Click "OK"
9. Click "OK" until all the My Computer properties windows are closed.

Assuming that you've already installed cvs.exe, you can now access your Sourceforge CVS tree.

Back in the times when HarryF and Glenplake took on the trying task of international collaboration, HarryF set up his environment variables just like this. And once that was done, he took all the work he'd completed so far and imported it into CVS like this:

cd \MyWork\the_project    
cvs import the_project vendor start

Here's what he did, line by line:

1. He changed to the directory where the project he wanted to add to CVS was located.


2. He imported all the work from that directory -- and everything below it -- to the CVS repository "the_project". He had to use "vendor start" unquestioningly at this point (read more about it here).

Once it was imported into the repository, HarryF renamed the directory "c:\MyWork\the_project" to "c:\MyWork\the_project_old" so that it wouldn't be lost in the check out of his first copy of the new repository:

cd \MyWork  
cvs co the_project

And as if by magic, the_project was restored to its original location! Notice that there are some extra directories within each subdirectory of the project, named CVS. These directories contain local information that CVS uses to keep track of your work -- don't mess with them unless you know what you're doing.

HarryF then discovered one of CVS's darker secrets: CVS doesn't handle binary files very well, including executables (.exe), images (.gif,.png,.jpg), and Shockwave (.swf) files etc. CVS assumes by default that all files are text files, and attempts to place things like revision code in them, which tends to have a disastrous effect on binary files. All of the .gif images HarryF had made and imported into the CVS repository were now scrambled and useless. What could he do?

Well, in general, before you import your project for the first time, it's a good idea to set up a cvswrappers file to tell CVS which file types are binaries. Alternatively, when you add new binaries to an existing project, you can also use "cvs add -kb myfile.gif" to tell CVS that the file is a binary.

HarryF discovered this through feverish consultation of the manual on cvs admin and how to recover from this disaster. He implemented it and -- hey-presto! -- his binary files were restored to their former glory.

Finally happy with the CVS repository, HarryF emailed Glenplake to tell him that all was well, and that it was time to merge the work he'd done with the main code. HarryF then decided he needed a break, and went out to start yet another argument with the mechanic who was supposed to be fixing his motorbike.