Helpdesk

TortoiseCVS is a free CVS client for Windows- it speaks the CVS standard for revision control of files (typically program source code). It can work with a local "repository" (where your files and information about revisions are kept), or as described in this document, access files kept on a Unix-based server over an ssh connection.

If you plan to make frequent use of CVS against an ssh server, please make sure to investigated the advanced ssh instructions to avoid having to enter your passwords for every CVS transaction.

Getting Started

First, download TortoiseCVS at http://tortoisecvs.sourceforge.net/. Run the downloaded installer to install TortoiseCVS on your system (administrative privileges may be required).

TortoiseCVS doesn't function as a separate program, per se. Instead, it acts primarily as an extension to the Windows file manager and provides context-sensitive actions that can be accessed via right-click access. For example, if you right-click on the desktop after installing TortoiseCVS, you should see two new entries: one called CVS Checkout and one called submenu called CVS. Preferences for TortoiseCVS can be accessed from this CVS submenu, but the defaults work fine for most purposes.

Creating a CVS repository

Before you begin using CVS to manage your files, you need to know where your repository will reside and initialize it for CVS use. This can be on your local computer, or in our case, somewhere on the Linux server. A convenient place is a directory named "CVS" in your home directory. Thus, first log into your Linux account and create a directory named CVS by executing CVSROOT=/home/jbruin/CVS cvs init (users of csh/tcsh will have to alter this syntax).

The above only needs to be done once for the repository and each repository can contain as many projects as you desire, so typically, it will only have to be done once ever.

Defining and new module

You are now ready to import files into CVS. Typically, these files will reside in a directory on your Windows workstation and in CVS parlance will be called a module. Right-click on this directory and under the CVS submenu, select Make New Module...

You'll then be presented with a complicated dialog requesting details for where and how to store your files. Fill in as follows:

• Protocol: select Secure shell (:ext:)
• Server: enter calypso.genetics.ucla.edu, or the appropriate address of the Linux server
• Repository folder: enter /home/jbruin/CVS, or the appropriate full path to your repository.
• User name: enter your username for that server
• myprogram: enter a name for this module. Typically, this would be the name of your program. Generally, it is advisable to exclude spaces and punctuation marks in your module name.

Once everything is set, click the OK button. Note that you need to enter this information only once per module; subsequently, you can select the module details from the menu that appears at the top of this window.

If everything has been entered correctly, you should see a log window appear and then a password dialog. Enter your password (it may request it more than once). Eventually, you should see a success message - your new module has been created.

Adding files to your module

Next, you need to import all your files into the module (the step above just prepared the module). Right-click on the directory again and this time select CVS Add Content.... You may notice that the icon for this directory now appears different, probably with a green mesh overlay - this is the indicator that this directory is under CVS control. Once you've selected CVS Add Content..., you be presented with a dialog listing all of the files in that directory. Go through this list carefully and uncheck any files that do not need to be revision controlled. Typically, only source files need revision control - compiled binaries, temp files, object files, almost all binary format files shouldn't be placed in CVS. Take care to do this during the importing step as removing files later is troublesome and will continue to take up space in your repository (since it is a permanent history of your module's files).

Once you've properly marked the files you want to import, click OK. Again, you will be asked for your password, possibly many times (once each for each subdirectory). Enter it as often as it asks. Eventually, you should see a success message.

Commiting your first version

Now that CVS knows about your files, you must commit. Commiting is CVS's way of "saving" changes and actions, so until you perform a commit, nothing has been "saved". In our case, we've told CVS that we have a bunch of files for this module, and now we have to tell it to make those additions permanent. To do so, again right-click on the directory with your files and this time select CVS Commit.... This will look similar to the file addition dialog above, but there will be an additional box where you should type in a comment describing what you are committing. Here, we are simply importing all files, so the comment can be "Importing". When you later subsequently commit changes to files, you should describe in more detail what changed between commits.

Basic Usage

After making the initial commit, your project and all the specified files are now under CVS management. For the most part, this is not something you have to give much thought to as you work with your files. However, there are two actions you should keep in mind: updates and commits.

A CVS update attempts to sync your local directory with that in the repository and report any changes. Typically, you will see 3 classes of files when you do a update:

1. Files that match between your local copy and the repository (ie no changes have occurred)
2. Files that you have changed but not yet commited - these will appear with a flag M and will not be uploaded to the repository until you do a commit
3. Files that have changed in the repository but your local copy is out of date. This will occur, for example, if two or more developers are working with the same repository and another developer has commited some changes since the last time you did an update. In this case, these files (marked U) will be downloaded to your local copy of the module. This will also occur if you are missing a file from the repository (for example if you deleted one by mistake, or if another developer added one).

Another, less common, occurrence is a combination: you have modified your local copy of a file and another developer has committed changes. In this case, CVS will try to reconcile both sets of differences and will warn you of the circumstances. Typically, it will mark areas of the file in question where conflict arises and you must reconcile them in some way.

One other action that will frequently arise is the addition of a file. Simply creating a new file in your local copy of the module is not sufficient to make it part of CVS management: you must add it (right-click and select CVS Add) and then commit it as usual. Conversely, don't just delete a file from your local copy to remove it- when you next execute an update, it will re-appear. Instead, right-click and select Remove from the CVS submenu.

Advanced SSH configuration

During large updates and commits, you may find yourself having to enter your password quite often, depending on how the number of subdirectories in your CVS module. With a little work, you can set up ssh to only require you enter your password once per session by using ssh's key-based authentication.

First, you will need a couple of additional ssh tools. Visit the PuTTY home page and download the following 3 programs:

• PuTTY
• Pageant
• PuTTYgen

Creating your keys

Place these 3 executables in a directory somewhere (for example C:\putty). Run puttygen first. Select the SSH2 RSA option at the bottom of the screen, then click the Generate button. This will take a while, and you'll be asked to move your mouse around. Once this is done, enter a passphrase twice, where indicated. This should be different from your password, and should be a sentence. For example My username on calypso is jbruin (Do not use this, or a variant, as your passphrase!).

Now save your key by clicking the Save private key button and storing this in a safe place (for example, in My Documents). Remember where you saved this file. If you lose it, you'll have to go through this again.

Next, copy the contents of the text box near the top, the one that looks like gibberish, into your clipboard. You will need to create a file in your Unix home directory at ~/.ssh/authorized_keys2 with this as its contents. Make sure that the directory and file have restricted permissions by executing chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys2.

Finally, configure putty to mimic the TortoiseCVS connection to the CVS server. Run putty and in the configuration, select SSH for the protocol, enter your hostname (ie calypso.genetics.ucla.edu), enter a session name, and save your settings.

Using your keys

Now, run pageant, which is the authentication agent that will manage your keys. After double-clicking on pageant, it will appear in your Windows system try (usually on the right side of your task bar). Right click on it and select Add Key. You'll then be asked to locate your private key file and enter your passphrase.

If everything has been configured correctly, you should be able to perform CVS actions without having to enter your password each time. Instead, pageant will manage the connections and provide the authentication credentials for the keys you created.