Using CVS with Windows

Note that these instructions refer to using the command line version of cvs on Windows as available from the FreeBMD web site. It does not cover WinCVS, a Windows interface version.

This page must be read in conjunction with the FreeBMD development process which explains how tasks are managed in the FreeBMD project by the use of PTS (Problem Tracking System).

What is cvs?

cvs is a source control system that enables several people to be working on the files of a project at the same time. It ensures that two people cannot inadvertently edit the same file at the same time and interfere with each other. Unlike some other systems, however, it doesn't do this by locking out a second updater but by merging together any changes that are made simultaneously.

The master copy of the files managed by cvs is called the repository and for the FreeBMD project this is on the development machine under /home/cvs.

In order to use cvs you have to interact with the development machine using a secure protocol. This protocol is normally called ssh (secure shell) although strictly ssh is a command line shell that uses the secure protocol.

Two methods of using the ssh protocol are described:

By using the basic ssh program
By using the PuTTY implementation of ssh, called plink

The advantage of the latter is that you don't have to type in your passphrase (or password) for each cvs command. PuTTY also provides a secure terminal emulator and secure copy.

Using these instructions

A lot of the activities described in these instructions are done using a DOS Window, that is a command line interface to Windows. In these instructions commands you have to type and information that is presented to you is in a fixed space font like this.

Where you have to supply information you have defined then italic font is used. For example, if it says type

set HOME=cvs-home

you have to replace cvs-home with what you have decided cvs-home will be, for example

set HOME=c:\FreeBMD

You should treat all commands as case sensitive.

Getting the software

Get the cvs software, and associated routines including ssh, by downloading this file from FreeBMD.

If you wish to use PuTTY download it from here. This provides

putty a secure interactive terminal
pageant an authentication agent that saves your passphrase for a session
pscp a secure copy method (implements scp, secure copy)
plink a version of ssh

Installing the software

Unpack the zip file cvs_ssh.zip downloaded from the FreeBMD site. You can put the executables in any convenient directory provided it is mentioned in the PATH environment variable. So you might put it in c:\Program Files\cvs and put that file on the path.

Note that this is version 1.9.10 of cvs. There is a later version, 1.11, available from www.cvshome.org, but this has not be validated with the FreeBMD repository.

For PuTTY download the executables (putty.exe, plink.exe, pageant.exe) from the download site and install them in an appropriate location, say c:/Program files/PuTTY. You will probably want to put them in the Programs Start menu as well.

The first steps

In order to edit the FreeBMD project files you must download them from the repository. Create a "home" directory in which you are going to keep the files. We'll call this directory cvs-home (so replace cvs-home with the name you have chosen in these instructions). It might be something like c:\FreeBMD.
Set the environment variable HOME to this directory, e.g.:

set HOME=cvs-home

but replace all backward slashes with forward slashes (e.g. c:/FreeBMD). You'll probably want to set set this environment variable in your logon environment so it is available automatically.
Run ssh-keygen.When prompted for the file in which to save the key accept the default offerred. It is most important that the file is literally called Identity.pub and is in cvs-home\.ssh. When prompted supply a passphrase (password) that will be used to authenticate your use of ssh.
Send the file called Identity.pub to Dave Mayall. This file contains your public key. In the same location ssh-keygen will have stored a file called Identity. This is your private key which enables you, and only you, to authenticate messages signed with your public key. Just in case you noticed it there!
Dave will set up a login (referred to as yourname below) for you on the FreeBMD development machine.
It would be wise to get Dave to set you up to be mailed with all cvs commits (see below).
Do not re-run ssh-keygen unless you need to create a new key to start again at step 4, because it will overwrite your key and you will no longer have access to the server.

Preparations for using cvs

These instructions refer to the use of ssh - for plink see the section Using plink.

Make sure HOME is set as above.
Set the CVS_RSH environment variable:

set CVS_RSH=c:\Program Files\cvs\ssh
Download the source from the repository by navigating to your cvs-home directory and running the command:

cvs -d yourname@test.freebmd.org.uk:/home/cvs checkout UKGEN-FreeBMD

You will be prompted for the passphrase you gave to ssh-keygen. This will cause the files in the repository to be download into your home directory below a directory called UKGEN-FreeBMD.

Identify the cvs home

In the preceding section we identified where cvs should find the files in repository with the -d option, i.e. -d yourname@test.freebmd.org.uk:/home/cvs. However, cvs provides three methods of doing this and their interaction can cause some problems! The three methods are:

The -d option
From the file CVS\root in every source directory below HOME
From the environment variable CVSROOT

They are used by cvs in this order. The file CVS\root will be created when you do the initial checkout. This can cause a bit of a problem if you want to change it latter, which you might if you want to change from ssh to plink - more about this later!

Running CVS

This section describes, in outline, how to use cvs. It is obviously not intended to replace the cvs documentation but to indicate which of the many commands and options will be used most often and should be mastered first.

There are two ways you can use cvs - which one you use depends on the kind of changes you will be making:

independent: changes made by different people are done independently and cvs merges the changes - this is the method used for source and web page changes
cooperative: a file is normally only edited by one person at a time, or multiple editors will cooperate on the changes - this is the method used for district map changes

The following assume have already downloaded the files controlled by cvs (as described here). They also assume you have opened a DOS window and have navigated (using the CD command) to the directory in cvs-home containing file

Independent

The following are the most common operations that you can do on files in this mode :

Get the latest version of a file with cvs update file
Get the latest version of all files in the directory with cvs update
Find out the status of a file (i.e. what is the latest revision in the repository and is your version the same) with cvs status file
Find out how your version of a file differs from what is in the repository with cvs diff file
Find what has happened to a file with cvs log file
Commit changes you have made to a file with cvs commit file
Create a new file with cvs add file

You will be prompted for your passphrase (as defined to ssh-keygen) when you execute each command.

So the normal method of making changes to a file is

Get latest version: Do cvs update file to ensure you have the latest version
Make changes: Edit the copy of the file on your machine
Get status: Do cvs status file to check if anyone else has changed the file in the meantime
View differences: Do cvs diff file to check your changes by seeing the difference between your modified version of the file and the one in the repository
Commit changes: Do cvs commit file to make your changes to the repository - cvs creates the next revision number of the file. If someone else has made changes since you did the update, cvs will attempt to merge the changes. If there is a conflict it will report this for manual resolution.

Note that with commit you will be prompted for a message by Notepad opening up. Type in a description of the change you have made, save (ctrl+S) and exit Notepad. Include the Task identifier (TID) and brief explanation. This message will be sent to all users registered with cvs so they know what is going on. Alternatively, instead of inputting the description in Notepad you can use the -m option, i.e. cvs commit -m "message" file where message is the description you would have typed into Notepad.

You must always run the above from only one machine. Do not be tempted to update from one machine, copy to another and commit from there.

Cooperative

With this method of working the files on your machine are read only and you will not be able to change them until you have used the cvs edit command as described below.

The following are the most common operations that you can do on files in this mode :

Find out who else is editing a file with cvs editors file
Indicate you are going to edit a file with cvs edit file.
Indicate you wish to abandon edits you have made to a file with cvs unedit file.
Commit changes you have made to a file with cvs commit file

You will be prompted for your passphrase (as defined to ssh-keygen) when you execute each command.

So the normal method of making changes to a file is

Find status: Find out if someone else is editing a file with cvs editors file. If so, you will need to negotiate with them, or whoever is co-ordinating the editing activity, before proceeding.
Get access: Indicate you wish to edit a file with cvs edit file. This makes the file read/write and informs other users that you are going to edit it. If someone else starts to edit the file (they shouldn't) you will be notified by email.
Make changes: Use whatever editor is appropriate to change the file and save the result.
Cancel changes: If you decide to abandon the changes you have made, and revert to the orignal version, do cvs unedit file. You will not be able to edit the file again until you have done a cvs edit file.
Commit changes: Do cvs commit file to make your changes to the repository - cvs creates the next revision number of the file. You will not be able to edit the file again until you have done a cvs edit file.

Testing and deploying Changes

The way in which a change is tested and deployed (i.e. put on the live system), including the use of PTS, is described in the FreeBMD development process. The description in this section is just a summary and not a substitute for reading and understanding the process.

Having made a change to a file in the repository you will need to see if it works. You can do this on the test site http://test.links.org:8080 but first of all you need to get the file(s) you have changed installed there. Do this by going to the following link http://test.links.org:8080/devt-cgi/update. You will see a list of files displayed, amongst which will be the file(s) you have done a cvs commit on.

You can now go to http://test.links.org:8080 and test your changes. Once you have tested your changes, and the person who initiated the change has also tested it (as indicated by PTS "Tested OK" status), you can deploy the change. To do this navigate to the directory containing the file and execute the following:

cvs tag Ttid file

where tid is the task number the change is relating to and file is the file you are deploying.

Now go to PTS and change the status of the task to "Ready to deploy" and assign it to Dave Mayall. It is also useful to record in the task comment the name and revision number(s) of the file(s) that implement the change.

Bits and pieces

Creating a new executable file

Creating a new file will not occur very often, but when running cvs from Windows there is a catch in creating an executable file, e.g. a perl script. Namely, it will not be executable!

Whatever the Windows permissions are on the file that is created (using cvs add ...), it will not have the executable bit set on the server. If you have access to the development machine you can go into source and add the execute permission manually ... or get Ben, or Dave, or Graham to do it for you!

Binary files

Binary files (e.g. image files such as .gif) are handled specially by cvs. It doesn't try to report differences when you commit a new version, for example.

If you create a binary file use the -kb option on the add command, thus

cvs add -kb file

However, there is a problem! When you do the first commit on the file cvs does put the whole of the binary in the commit mail message. Therefore, the socially responsible thing to do is to make the first commit a dummy file and then commit the real file as a second commit.

General update

Every so often it is worthwhile doing a general update to get the latest copies from the repository, especially new files. Only changed or new files will be downloaded. To do such an update use the following when in directory cvs-home

cvs update -AdP rootsweb-FreeBMD2

Creating a new directory

It's unlikely you will have to create a new directory in the repository but if you do, get help! Although cvs add can be used to create a directory it will not automatically be added to the test system.

Getting a previous revision

To get a previous revision of a file use

cvs update -r revision -p file

which will cause revision of file to be piped to standard output. The command above will display the revision of the file - but you probably want to store it somewhere! So do this:

cvs update -r revision -p file > DestFile

where DestFile is the file name you want the revision stored in.

Reverting source

Under certain circumstances you may want to abandon edits you have done and revert to the current version in the repository. If you are using cooperative mode you can do cvs unedit but in independent mode the easiest way to do this is to delete the file (or copy it somewhere else) and then do cvs update file.

Note that the -C option on update, which overwrites your version of a file with the one in the repository, is not available in version cvs 1.9.10.

Deleting a file

This only applies to independent mode. It's unlikely you will often want to delete a file, but if you do there is a specific process to follow if the file is live on the server. To delete a file called file:

cvs tag -d BMD_LIVE file delete local copy of file cvs remove file cvs commit file

Documentation

The documentation for cvs 1.11 is available from www.cvshome.org. Although this is a later version of cvs than the one you will be using, this documentation represents a valuable source of information, although it is not the easiest manual in the world to use!

Case sensitivity

File names in Windows are not case sensitive, whereas for the cvs repository, on UNIX, they are. Most of the time cvs manages to handle this transparently but sometimes using the Windows case insensitivity can catch you out. If you want to make things simple for yourself always treat the file names of files managed by cvs as case sensitive, even on Windows.

Presetting your environment

Rather than set the environment values each time you want to use cvs you can set them up in your default environment. To do this right click on My Computer on the desktop, then Properties. On the Advanced tab click on Environment Variables and enter the variables in the top pane, i.e. HOME, CVS_RSH. In the bottom pane edit the path variable to add c:\Program Files\cvs

Abbreviations

Although there are abbreviations for the commands it is probably best to avoid them, at least initially. For historical reasons the abbreviation for commit is ci whereas the abbreviation co is used for checkout, so one can get confused!

Using plink

As mentioned in the previous section, with ssh you will be prompted for your passphrase at each command execution. This can get a bit boring and by using plink (with pageant) you can supply your passphrase only once per session.

Create a PuTTY saved session

Run putty and set up the following parameters:

	hostname	test.freebmd.org.uk
	port	22
	protocol	SSH

CliCK on the + next to Connection and then click on SSH

Preferred SSH protocol version 1

Private key for authentication cvs-home\.ssh\Identity (or wherever you stored your private key - see here)

Click on Session and type a name (e.g. cvs) in the Saved Sessions box and click on Save. We will refer to this name as cvs-session below.

Note for Windows XP users: The first time you use PuTTY you should change the default encryption cipher selection policy to 3DES.

Exit by clicking on Cancel

Create a session

Run pageant. In the task bar at the bottom of the screen a computer with a hat on will appear. Right click on this and select Add key. Navigate to your Identity file (this will be cvs-home\.ssh\Identity) and click on Open. Type your passphrase when prompted.

Note that the security of FreeBMD is now dependent on the security of your machine. Ensure you have a secure logon and timeout/close your machine when not using it.

Change cvs protocol

Change the environment variable CVS_RSH to point to plink, for example:

set CVS_RSH="c:\Program Files\PuTTY\plink.exe"

Change cvs directory

You only need to worry about what's in this section if you did a cvs update using ssh and now want to change to plink.

In order to run any of the cvs commands using plink instead of ssh include -d cvs-session:/home/cvs where cvs-session is the name you saved your PuTTY session under.

For example:

cvs -d cvs-session:/home/cvs status file

If you want to change from ssh to plink permanently you will probably want to make the above directory the default. This is a bit awkward because you have to either change or remove the CVS\root files (i.e. the files named root in the directories named CVS) in each of the directories on your machine below the directory you specified in HOME (as described here). The easiest is probably to delete them all and

set CVSROOT=cvs-session:/home/cvs

FreeBMD Main Page

© 1998-2008 The Trustees of FreeBMD (Ben Laurie, Graham Hart, Camilla von Massenbach and David Mayall), a charity registered in England and Wales, Number 1096940. We make no warranty whatsoever as to the accuracy and completeness of the FreeBMD data. Use of the FreeBMD website is conditional upon acceptance of the Terms and Conditions

	putty	a secure interactive terminal
	pageant	an authentication agent that saves your passphrase for a session
	pscp	a secure copy method (implements scp, secure copy)
	plink	a version of ssh

	Preferred SSH protocol version	1
	Private key for authentication	`cvs-home\.ssh\Identity` (or wherever you stored your private key - see here)