This document evolved as an introduction for my friends and co-workers on how to get CVS working with SSH, and specifically, how to do so without having to type passwords all the time. All of the discussion on this page is strictly about using various flavors of CVS clients via SSH, but if you follow my discussion on secure yet password-free SSH, your CVS usage will be transparently both secure and password-free as well.

CVS Background / Using SSH with CVS

CVS is the Concurrent Versions System. CVS is a software configuration management (SCM) tool. It allows developers to collaborate on projects transparently across networks and client platforms. It works best on plain text files, but can also handle binary files. Some functionality will be lost on binary files as CVS can not perform the same operations on these files. For instance, CVS has no meaningful way of displaying the difference between two images.

A replacement for CVS, Subversion is being developed and looks very promissing - I have not yet used it, but have a project where we might very soon.

For more information, you might want to visit the CVSHome pages for background if you've never used CVS before. Also, here is a good introduction to how best to use CVS. That page is the source of some of this information.

What version of CVS should you use?

On UNIX, the only real choice (IMO) is the GPLed CVS available from CVSHome.org. For a graphical front-end to CVS, take a look at gCVS which is an X based CVS client; I've not used it as I use pcl-cvs mode inside of (X)Emacs.

On most Win32 platforms, I recommend using the either the version of CVS that comes with CYGWIN, which is the same as found on most UNIXen. Alternatively, you can get the Windows Explorer integrated TortoiseCVS. I know some people use WinCVS But I haven't used it in some time, nor have I tried to get it to work with SSH in any fashion. I'm not going to go into installing or configuring any particular version of CVS, but both work (largely) out-of-the-box with SSH, and specifically with ssh-agent or putty-agent (see my secure, password-free ssh page for more info on those tools). Where needed, I will document specific configuration issues.

Using a command-line CVS via SSH

No matter what tool or flavor of CVS you use, CVS needs to know that it should use SSH to get to the CVS-Repository. For UNIX/CYGWIN flavors of CVS, this simply means setting the value of the CVS_RSH environment variable to be the ssh-client program, typically just ssh. Most often, this can be done in your login-shell configuration script.

For GUI tools like TortoiseCVS, there is often a preference to set the ssh-client program.

  1. Make CVS use SSH: Add the following to your ~/.bashrc shell configuration script. 

    export CVS_RSH=ssh

    You will need to source (re-read) your configuration script now, or log-out and back in. If you use a different shell, you will need to modify that line for the appropriate syntax of your login shell. With that simple setting, CVS will be able to determine when to use SSH depending on the repository location (i.e. if it is a remote repository, CVS will use SSH). If the repository is local, then CVS will not use SSH.

  2. Tell CVS where your repository is: type this in a shell window.

    export CVSROOT=user@cvs.server:/path/to/repository

    That tells all instances of CVS (in this shell and sub-shells) that the root of the CVS repository is on the machine cvs.server in the directory /path/to/repository and that to get there, login to the server (via SSH) with the username user. Of couse, replace the various portions of the example with your username, server and path.

    The repository location can also be specified at the commandline using the -d switch. It is not a requirement that $CVSROOT is defined, as CVS largely ignores this variable. Once you have created your working directory, CVS will use the information about the repository that is stored in your working directory

  3. Alternative - use command-line flags: 

    mkdir test
cd test
cvs -d :ext:user@cvs.server:/path/to/repository co cvs-module
# [..creates cvs-module and CVS directories..]
cd cvs-module
cvs status main.c
# [..]
cvs log main.c
# [..]

    ...where user@cvs.server specifies your user name on the CVS server and the name of the CVS server, /path/to/repository specifies the location of the repository on the server, and cvs_module specifies the name of the module in the repository that you want to checkout into your sandbox. As you can see, there is no need to supply the location of the repository, except the first time, as long as you are issuing commands within a working directory that holds this information in the CVS/ directories.

Furthermore, if you follow the instructions for secure, password-free ssh, when you use CVS in your CVS sandbox, it will refer to the remote server and reach that server via SSH, all without asking for passwords.

Using TortoiseCVS

TortoiseCVS is a Windows Explorer integrated CVS tool. It adds context menus to files and directories in CVS sandboxes for common CVS commands such as commit and update. Other CVS commands can be issued via a GUI interface available from the Windows START menu.

To install TortoiseCVS, first fetch it from the TortoiseCVS home page. The installer is quite standard and straight-forward, but will almost assuredly require a reboot.

Configure TortoiseCVS

Open the TortoiseCVS Preferences by either navigating the Windows START menu or by right-mousing in any Windows Explorer window to the CVS » Preferences option. I recommend possibly adjusting the following, as you see appropriate:

  1. Advanced tab

    • Sandbox: UNIX

  2. Policy tab

    • Check: Allow Network Drives
      — only if you really need access to sandboxes not on local drives; this will undoubtedly cause delays when creating the context menus in explorer.

Neither of these are required, but I recommend them, at least if you are working on a project that has any UNIX users or you use reasonable editors like Emacs.

Using TortoiseCVS with PuTTY-Agent (Pageant)

First, follow the instructions for secure, password-free ssh to set up PuTTY, generate your public/private keys, publish the keys to the server, and start PuTTY-Agent. If you have done all of that, TortoiseCVS should just work out-of-the-box with PuTTY and you should not be required to type any passwords.

If you have troubles, some people have recommended using the version of Plink that comes with PuTTY itself rather than the version bundled with TortoiseCVS. I have had the opposite experience in that I cannot get the PuTTY Plink working with TortoiseCVS and have to use the bundled version.

Using TortoiseCVS with Cygwin SSH and ssh-agent

If you already use Cygwin, or you want to use my automatic proxy detection script, then you probably want my tortoise-ssh.bat batch-file. Really all that batch file does is invoke a Cygwin bash shell so that your environment is setup correctly, including the PATH variable and potentially the ssh-agent environment variables. The latter is required if you have followed the instructions for secure, password-free ssh, and want to make use of that feature.

To use this batch script, place it in a reasonable location on your computer. Then set the value of SSH Application in TortoiseCVS to point to that location. Everything else should just work, but please read the comments in the batch file to configure in your environment.

Troubleshooting TortoiseCVS

If you get something like this: 

cvs checkout: warning: unrecognized response `Unable to open connection:' from cvs server
cvs [checkout aborted]: end of file from server (consult above messages if any)
Error, CVS operation failed

Ensure that you have a version of CVS in your PATH on the remote server where the repository lives.

TortoiseCVS Caveats

I would NEVER recommend using this TortoiseyCVS, or any Windows-based CVS tool, directly operating on a file-repository on a UNIX-style file server (e.g. via SAMBA) - I've had problems with the CVS client messing up permissions on files in the CVS repository. Always resort to using a SSH tunneled access; it works nearly as fast and doesn't have the same problems.