Using CVS to Update a Web Site - A Guide For Web Developers

The Problem

Let's say you're one of six people of varying skill levels working on a web site. After somebody else uploads a change, you notice the site is totally broken. Worse, you don't know who did it, and you don't have a backup of the files they changed. AAAAGH! Four hours of phone calls and cursing later, you have the web site working again. "There's got to be a better way," you say -- and there is. You can use a revision control system like CVS to tell who uploaded what files, exactly what they changed in those files, and revert the changed files back to good versions in minutes.

CVS - the Concurrent Versioning System

CVS is a program that acts like FTP with a built in backup system. It makes it easy to upload or download your whole site all at once, and helps you stay in sync with the changes your fellow team members are making to the web site.

It's free software, and runs on just about any kind of computer out there. The basic package consists of a program which is run from the operating system's commandline, but there are many graphical versions, including: WinCVS for Windows, MacCVS Pro or MacCVSClient for the Mac, LinCVS for Linux, jCVS for Java, and even versions you can use from a web browser. They are all versions of CVS, so sometimes people say "CVS" when they mean "WinCVS or whatever you have".

CVS is complex because it can handle very complicated situations; yet it's simple at heart, and most people using it to maintain a web site will never need to learn any of the tricky stuff. What follows is a quick guide to the essentials of using CVS on Windows.

Setting up WinCVS

Download the latest version, currently "WinCvs11b16.zip", unzip it to a temporary directory, and run setup.exe in that directory to install it.
Create an empty directory named D:\work. This is where you will store your copy of the web site you're working on.
Run WinCVS (it should have an icon on the desktop).
Set up a few settings:
- In "Admin / Preferences / General", CVSROOT should be the access string given to you by your CVS administrator. It will look something like this:
```
:pserver:myname@myserver:/repository
```
  where myname is the CVS account assigned you by your CVS administrator, myserver is the IP address or hostname of your CVS server, and repository is the path on the server to the repository created by your CVS administrator.
  In that same panel, in the "Authentication" pulldown menu, you may need to pick "passwd file on the server".
- In "Admin / Preferences / Globals", "Checkout Read-Only" should be UNCHECKED (so you can edit your copy).
- In "Admin / Preferences / WinCvs", "Home Folder" must be a valid directory (e.g. C:\WINDOWS or D:\WORK); this is where it stores your password file.
Tell it where your files will be on your disk: Click on the binoculars icon to the right of the combo box on the menu bar; select the empty directory D:\work you created earlier
Try out the settings by logging in; pick "Admin / Log In". It will prompt you for the password assigned to you by your CVS administrator.
Grab the files: do "Create / Checkout module", and fill in the "Module Name" field with whatever the CVS administrator tells you to.
Note: WinCVS appears to take about three times longer than jCVS to check out files (54 seconds vs. 20 seconds for 660 KB); I've filed a bug report.
Fish will swim in the lower right of the window while the files transfer. When the fish stop, and it says "command finished successfully", hit F5 to update the display, and your module name should show up in the left hand "Modules" window. (If it doesn't, click the "Explore" tab on the left hand window, and navigate to the D:\work directory.)
The left hand window is a tree view of your site, and the right hand window is the files and folders in the folder selected in the left hand window. (Just like Windows Explorer.) The right hand window can be sorted by filename, by time, or by version number; click on the column you want to sort by. (You may need to narrow some of the columns to get them to all fit on a small display.)
You now have a copy of your site's files in a subdirectory of D:\work, and can edit them as you like. Make sure to only edit the copies in the D:\work directory if you want to upload them with CVS!

Changing a page and uploading the change

Get the latest copy of the web site files by "Updating" your copy; in WinCVS, you do this by selecting the file or folder you want to download, then clicking on the button that looks like a downward arrow. It's always ok to download the whole site; you'll only get what's changed since your last download.
Go ahead and edit any of the files under D:\work using your favorite tool, be it notepad or be it Dreamweaver.
To avoid breaking the site, test your changes locally before you upload them. You can browse through your local copy of the site just as if it were online; open up D:\work in your web browser, open up the subdirectory containing your site, and click on index.html. The site should occur in all its glory.
Upload (or, as CVS calls it, "Commit") your changes; in WinCVS, you do this by selecting the folder or file you want to commit in the right hand window, then clicking on button that looks like an upward arrow. The program will ask you to type in a short description of your changes. Keep it brief, but understandable - people will actually read these. It's always ok to upload the whole site; only the files you have changed since your last upload will actually be sent.
If somebody else has been changing the same page as you at the same time, CVS will try to merge the changes automatically. If the changes overlap, it will ask you which changes to keep. If this happens, call your CVS administrator and/or read the documentation to learn how to handle it. (Programmers do this all the time; hopefully you won't have to.)

Use relative links!

To preserve your ability to test your site locally, DO NOT use absolute links (e.g. "http://www.hostname.com/" or "/index.html") when linking to another page on the same site. Instead, use relative links (e.g. "index.html" or "foobar/bletch/index.html" or "../index.html" -- i.e. not starting with http:// or a slash).

Avoid destructive tools!

Caution: don't use any editors such as Microsoft Front Page or Microsoft Word that modify the whole file every time you open it -- that makes it very hard to see what has changed from version to version of a file, and causes trouble if two people edit the same page concurrently. (It's hard to merge overlapping changes.)