Using CVS to Update a Web Site - A Guide For Web Developers
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
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,
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:
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).
See also HTML Tips: Relative v. Absolute Pathnames,
How to Use Links Effectively:
Absolute vs. relative links
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.)
If you have trouble, or want to read further, more documentation for WinCVS
is available at www.wincvs.org/doc.html.
My guide for
setting up a CVS server may also be interesting to advanced users.
documents how to set up SSH and CVS on Windows.
Last updated: 28 November 2000
Copyright 2000 Dan Kegel
[Back to CVS]