Last changed 30 March 2002
This document attempts to provide a few personal insights on using CVS on a Windows client based on my observations and experience. It is a personal "mini-HOWTO" that I use when I need to set up a Windows workstation to use CVS.
I've cleaned up the notes and put them on the InterNet in case anybody else might benefit from them. This does not attempt to be an installation guide, reference manual, or FAQ.
Use the information in this document at your own risk. Don't come crying to me if, in the course of using this information, you fry your computer, erase your hard work, or telepathically impregnate your cat!
| Tor Langlo | Pointed out initial deficiencies. |
| Gene Myers | Provided useful information on VSS. |
| Christopher A. Brooks | Pointed out that the original setup was unnecessarily complicated; only one version of ssh is needed. |
| Dale Wilson | Educated me on VSS' ability to do diffs on directories, etc. |
| David Corcoran | Pointed out bad links. |
CVS is an Open Source revision control program that has become the de facto standard for revision control in many circles. It was written for Un*x-like operating systems. In true geek fashion, Windows GUI clients were created to fill the vacuum.
There are a few tools that work with CVS on a Windows client machine. Each has its own use. To get the most out of the document, you will need the following:
There are many other good free and for-fee differencers on the market.
The client/server nature of CVS is very convenient. Here we will not be using the CVS server because its protocol is not very strong cryptographically. We will be using CVS directly off of the server, using ssh (secure shell) to provide heavy-duty encryption over the InterNet.
The tools appear to be robust and bug-free so far. As with all software they have their quirks. The critical part is setting up ssh correctly. It appears that all problems begin and end with the collision between the Un*x and Windows way of doing things. Some smart people have handled things pretty intelligently, so daily use is quite transparent once set up correctly.
Install WinCVS. You can download it from the official SourceForge site. I've only been able to get the 1.3 betas to work, so you'll find no information for v1.2 here.
Note that the README suggests adding the WinCVS install directory to the PATH environment variable.
See Resources below for additional help. (It should be easy: unzip and run the installer.)
WinCVS uses Python as a scripting engine. This in nominally optional, but I've not been able to get WinCVS 1.3b6 to run without installing Python (v2.1.1).
Use the installer from the TortoiseCVS web site. I personally don't like the default icons. You may wish to see the TortoiseCVS FAQ for more æsthetically-pleasing icons.
I would suggest adding the TortoiseCVS install directory to the PATH environment variable so that its implementation of ssh is available.
TortoiseCVS supplies its own ssh. We will set this up, and tune WinCVS to use this version of ssh. These will be treated individually.
Both CVS and ssh will need a directory in which they can find and store configuration information. I created a directory called C:\home.
Set the HOME environment variable to this directory.
Create a subdirectory in %HOME% named ".ssh" (four characters; note the leading period). You may need to drop to a DOS prompt to do this. Explorer refused to let me create a directory with this name.
Simon Tatham has put together a collection of small, useful executables for using the Secure Shell protocols under windows. These are all distributed under the MIT License, which is a derivative of the BSD License.
I've taken the following steps to set up these programs up on my machine.
| PuTTYgen | Used to generate cryptographic key pairs. | This is required for setup. |
| PuTTY | A ssh-enabled terminal emulator | These are not required for normal operation of either WinCVS or TortoiseCVS, but you can use them to access your CVS server over an insecure network, such as the InterNet. Please do not use telnet, rsh, rcp, etc. to access any machine over an insecure network. These programs are insecure. Use these two programs if an insecure network lies between your workstation and your CVS server. |
| PSCP | A secure file copy program |
chmod 700 ~/.ssh). ssh may refuse to work if this
directory is group or world readable.
For the curious, steps 1-6 are analogous to the Un*x command
ssh-keygen -t rsa -f ~/.ssh/identity
This document assumes that the CVS server is set up with individual developer logins. Ensure that all developers have an account.
To enable automatic logins on the server, you'll need to alter the configuration file for OpenSSH.
/etc/ssh/sshd_config and set:
RSAAuthentication yes
Leave RhostsAuthentication and RhostsRSAAuthentication set to no.
TortoiseCVS' ssh appears to be a direct port of the Un*x ssh. It feeds off of the environment variable %HOME%.
Test for an automatic login to the CVS server with ssh -v -l username hostname to obtain a Un*x shell without needing to log in. If this happens successfully, congratulations! The biggest obstacle has been passed.
If you are prompted for a username, password, or otherwise don't get the expected result back automatically, then likely points of failure are environment variables, location of cryptographic keys, the remote ~/.ssh/authorized_keys file, or the remote sshd dæmon.
If your CVS server has a project already, you can do a quick test with TortoiseCVS.
 |  |
When you first bring up WinCVS 1.3, it will present you with its preferences dialog.
| The first dialog, shown in Figure 3, are the connection options. These operate similarly to the TortoiseCVS dialog.
I have noticed some strange behaviour with this dialog (it is still in beta stage). When I fill out the General tab and then close the dialog, it occationally messes up some fields when I open the dialog again. If I hit cancel, nothing bad happens. If I don't, then CVS operations fail. This appears to be a WinCVS bug. Any additional information on this is welcomed. |  |
| The second dialog, shown in Figure 4, show various options. Set them as you wish. If you have a slower connection to your CVS server, you may benefit from turning TCP/IP compression on. |  |
| The third dialog, shown in Figure 5, shows BeyondCompare being used as the visual differencing program. You shouldn't need to set the HOME folder, which will override the HOME environment variable. |  |
This dialog is otherwise available in the main menu under Admin | Preferences.
There is a tremendous amount of overlap between WinCVS and TortoiseCVS. TortoiseCVS focuses on ease-of-use, while WinCVS focuses on being a providing a complete wrapper around CVS. As a general rule, TortoiseCVS will provide for most daily operations. However, it is not wrap all of CVS' functionality. WinCVS is a complete wrapper around CVS, so it can handle the few remaining tasks.
This document will default to using TortoiseCVS unless WinCVS either provides the only way to accomplish a task or it has useful functionality.
CVS takes a client-oriented approach to revision control, which requires a mental adjustment from server-oriented version control such as Visual Source Safe.
The typical cycle consists of
A work space (sometimes known as a sandbox) is a location on your workstation that contains a copy of a project. One initial step, setting up the work space, must take place before any work can be done. This can be done with either WinCVS or TortoiseCVS. This involves designating the CVS repository and the module (project) within it.
Creating a work space will create data files and put metadata in a subdirectory named CVS. (Don't mess with the metadata; bad mojo.)
One can perform an "export" with WinCVS. This extracts data in a project per a checkout, but it doesn't extract metadata. Thus, an export can produce a copy of what is in the repository, but one can't use it as a work space.
This is something that is done frequently. This pulls the current version from the repository and incorporates it into your files. This will not destroy modified files. Changes will be merged into your copy if possible. See "Coördinating Code" in CVS for New Users.
Adding and deleting files is a two-phase process. One queues the add/delete commands on the local machine (a metadata operation), and then one commits the changes to the repository. One may physically create and delete files from one's work space, but this doesn't automatically alter the repository.
TortoiseCVS is the tool for adding files. It is reasonably intelligent about discerning between text and binary data, and will ask if it's not sure.
A commit alters the repository. File modifications, as well as files marked as new or deleted, are sent to the server.
If there are files or directories on which one would like to keep tabs, one may create a watch on a directory or file. This will send e-mail to the watcher's account on the server. To redirect the e-mail to another account elsewhere, one may create a file in the home directory with the name ".forward" (eight characters, note the leading period). This file should contain one line that contains the e-mail address to which e-mail should be forwarded.
I have not been able to get the notification configuration to work ($CVSROOT/CVSROOT/notify).
There is a "Preferences" program in Start | Programs | TortoiseCVS.
Alternatively, the program to run is stored in the registry in the user's Software key
.../Software/Beyond Compare/External Yes. There is a wonderful Python-based CGI program called ViewCVS. It has many features.
Be aware that if the CVS server is on the 'Net, Apache will have to be set up appropriately so that
These can be found at http://www.chiark.greenend.org.uk/~sgtatham/putty/.
http://www.cvshome.org/ Main home page
http://www.cvshome.org/cyclic/cvs/windows.html CVS on Windows page
http://viewcvs.sourceforge.net Home page
Amund Tveit has a page entitled A Minimalistic Guide to CVS with SSH
Open Source Development with CVS by Karl Fogel has provided me with some great "how-to" information. A large portion of the book is available on-line under the GPL.
http://devguy.com/fp/cfgmgmt/cvs/
http://devguy.com/fp/cfgmgmt/cvs/cvs_ssh.htm
http://devguy.com/fp/cfgmgmt/tools/install.htm
Version History:
Is there a way to browse the CVS repository on the remote server?
CVS vs. VSS Quick Comparison
Concept
VSS
CVS
Paradigm
Server Orientation
Client Orientation
Client Metadata
File (vssver.scc)
Subdirectory (CVS)
File Deletion
Must be careful. You can remove the Destroy permission in Administrator.
Used properly it operates like the CVS attic.
If you're an idiot like me your files will be gone forever.
Files moved to the "attic" where they are available for restoring old versions of a project.
Checkout (Terminology)
Checkout means to lock a file for exclusive access, allowing a user to edit the file.
Checkout means to create a work space, which copies data from the server and creates metadata in CVS subdirectories.
Update
Overwrites working files (with warnings).
Merges changes into working files.
File Change Status
One may use the shift key to display a dialog that allows VSS to diff directories.
All tools can show what files have changed or conflict due to the client orientation of CVS.
TortoiseCVS is integrated into the explorer. WinCVS also shows file change status.
Branch
Creates an entirely new project folder with its own copies of files.
According to the VSS on-line help one cannot have two branches that don't occupy two separate projects.
It's touted as a feature but IMHO it's annoying because it clutters the project tree.
One may use the shift key to activate a dialog to do a diff directly across projects.
Creates a branch within the file via versioning and tags.
Cross-branch diffs are trivial, especially with tools like ViewCVS.
WinCVS has a cool visual branch viewer.
Merge
Heck if I can figure this out! It's probably my ignorance. What little I've seen of the visual merge tool is nice.
Pretty straightforward, but one must watch one's P's and Q's to ensure the right versions are merged.
Conflicts are expressed as in-line diffs, which can be kind of annoying at times.
Resources
PuTTY, Plink, and Friends
WinCVS
Official CVS Home Page
ViewCVS
Other Links
Books
Useful Information at DevGuy
2002-03-30 Updated VSS information. Fixed bad links.
2002-03-14 Added note about Un*x ssh-keygen command.
2002-02-20 Made mention of occational quirky behaviour in WinCVS.
2002-02-15 Added link to Amund Tveit's paper.
2001-12-21 Fixed PNG graphics so they should show correctly for Netscape 4.77 on Linux.
2001-12-19 Fixed broken link to Karl Fogel's book site.
2001-12-12 Major overhaul of document to simplify installation. It's not that hard! Really!
2001-12-06 Directory of residence moved due to Windows limitations.
Added hyperlink to helpful CVS book.
2001-01-01 Updated VSS/CVS comparison notes. Thanks to Gene Myers for the information!
2001-11-28 Second pass over the document.
Added clarifications.
Corrected a mistake on a sample command.
2001-10-13 Made a note regarding where to put public key. Added blurb on what to change on the server to allow automatic logins.
2001-10-08 Published
2001-10-06 Created
