What is CVS?

CVS is a version control system. A version control system maintains an organized set of all the versions of files that are made over time. Version control systems allow people to go back to previous revisions of individual files, and to compare any two revisions to view the changes between them. In this way, version control keeps a historically accurate and retrievable log of a file's revisions.

More importantly, version control systems help several people (even in geographically disparate locations) work together on a development project over the Internet or private network by merging their changes into the same source repository. It ensures that two people cannot inadvertently edit the same file at the same time and interfere with each other.

CVS achieves this by maintaining a history of the files of a project as a series of changes. It stamps each change with the time it was made and the user name of the person who made it. Usually, the person provides a bit of text describing why they made the change as well. Given that information, CVS can help developers answer questions like:

Who made a given change?
When did they make it?
Why did they make it?
What other changes did they make at the same time?

Overview of Using CVS

CVS operates on Projects and the files within those projects. FreeBMD has five projects:

UKGEN-Dev: Contains development utilities
UKGEN-FreeBMD: Contains the FreeBMD sources
UKGEN-FreeBMD-Images: Contains the source for the image servers (which contain images of scans)
UKGEN-FreeCEN: Contains the FreeCEN sources
UKGEN-FreeREG: Contains the FreeREG sources

Each of these projects has a repository on the development machine which contains the source files and directories of the project (and the history of changes).

To begin working on one of these projects you first obtain your own working copy of the files and directories in the repository of the project. The process is known as checking out the project repository.
You make your contribution to the project by modifying these files and creating new ones.
This part of the cycle doesn't involve CVS directly. You modify your working copies of project files using a file editor on your local machine. You can save your edited files to test how your changes affect the particular project module you are working in without affecting anyone else's work on those same project files. Nothing you do affects other project participants until you merge your changes into the project repository.
You test and tweak your latest changes in your own workspace to make sure these work without breaking or corrupting the overall project.
Finally, you contribute back or check in your changes to the project repository, merging your work with the most recent working version.
Committing your changes to merge with other developers' work is the most powerful aspect of CVS. If a file that you have changed has also been changed by someone else, CVS checks to ensure that the two sets of changes do not conflict. If they do, it will warn you and you will need to resolve the conflicts possibly by liaising with the person who made the other changes.

This copy-modify-merge cycle is repeated throughout the life of the project by all contributing developers. CVS enables everyone to work on project files simultaneously, to stay up to date on the latest changes contributed by others, and to test how their own changes affect the overall project without interrupting other developers' cycles.

Preparing to use CVS

This section describes the steps you need to take in order to use CVS for the first time. If you have already done this you can skip to the next section.

In order to use CVS to amend the files of a project you will need three things:

The cvs client side software to install on your machine. There are a number of clients available but in this tutorial we will only discuss wincvs which uses a DOS interface (see the section on Using DOS Commands if you are unfamiliar with this). Some packages use a Windows Explorer interface (e.g. Tortoise CVS).
Communications software for communicating securely with the FreeBMD development machine using the SSH protocol. Again there are a number of packages that will do this but we will describe one, PuTTY. Installing a using PuTTY is described here.
A text editor to edit the files. There is a large choice from the simple Window Notepad and Wordpad to very sophisticated editors that understand the structure of different languages (e.g. html).

Having acquired and installed the above you will then need to do the following:

Decide where you want to hold your working copy of the project files. You should create a new folder on your hard drive for this; whilst the naming and location of this folder is arbitrary, a reasonable default would be 'freebmd' located under c:\ (i.e. c:\freebmd). We will refer to this directory as <freebmd> and where this occurs you need to replace <freebmd> with your own location (e.g. c:\freebmd).
Set up environment variables as described here.
Create working copy of the project files (the project repository) on your own machine as described here.

You are now ready to change project files!

Using CVS to edit files

There are two ways you can use CVS - which one you use depends on the kind of changes you will be making. The commands that you use, and the way that you use them, depends on which method you will be using so please following the links below. In the section following this one we will describe the commands in more detail.

Independent Mode
- Changes are made by developers working alone - this is the method used for source and web page changes. More than one developer may edit the same file and CVS merges the changes.

Co-operative Mode
- A file is normally only edited by one person at a time, or multiple editors will co-operate on the changes - this is the method used for district map changes.

CVS commands

The following is a summary of the CVS commands. Make sure you understand which mode you are using, Independent or Co-operative, as described above.

Important notes:

To issue one of the following commands your current directory must be the directory that contains your working copy of the repository (i.e. the directory we refer to as <freebmd>, e.g. c:\freebmd) or a directory beneath it.
If you do not specify a filename with one of the following commands the command applies to all files in your current directory and all directories beneath it.

cvs commit

Commit your changes into the repository. You will be presented with a page (probably in Notepad) to enter a short description of the changes you have made to a file (no need to put name or date, they are available automatically). You also do a commit after adding or removing a file; again a short description of why the file was added or removed should be provided.

cvs update

Get the latest version of a file from the repository. Your modifications to a file are never lost when you use update. If no newer revision exists, running update has no effect. If you have edited the file, and a newer revision is available, CVS will merge all changes into your working copy and will indicate if there are conflicts.

cvs status

Find the latest revision in the repository and compare it with yours. When you use status, one of a number of messages will be output. The following are the ones you are most likely to see:

Up-to-date: The file is identical with the latest revision in the repository.
Locally Modified: You have edited the file, and not yet committed your changes.
Unknown: CVS doesn't know anything about this file. For example, you have created a new file and have not run add.

cvs editors

Find out who is working on a file (Co-operative mode only).

cvs edit

cvs diff

Find out how your version of a file differs from what is in the repository. This is useful to see what changes you have made. Use cvs diff -w to ignore changes in white space, e.g. a change in indentation.

cvs log

fFind out what happened to a file in terms of when it was deployed and what changes have been made to it (and by whom).

cvs add

Create a new file. See Adding a file.

cvs remove

Remove a file. See Deleting a file.

Additional information

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 <freebmd>

cvs update -AdP UKGEN-FreeBMD

to update the UKGEN-FreeBMD project (or other project as appropriate).

Adding a new file

If you need to add a new file to the project use the cvs add command but see below if it is a binary file. The file will not actually be added to the repository until you do a commit on it.

Creating a new executable file

Creating an executable file does not cause CVS to mark the file as executable (since Windows does not have the concept of execute permission on a file). However, an automatic process has been installed in the CVS repository to take care of this in most cases. If the file has a shebang first line (i.e. starting with #!) and does not have at least one execute bit set then it will be marked as "executable for all". In other circumstances the execute bits will need to be set manually on the file in the repository; send an email to the tech mailing list if you do not know how to do this.

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 puts 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.

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. To do this type

cvs update -C file

Note that your existing version will be copied to a version with a name starting in .#

Deleting a file

To remove a file from a project, you must first remove the BMD_LIVE tag using

cvs tag -d BMD_LIVE file

after which you can then remove the file itself (if you do not remove the BMD_LIVE tag, deleting the file will not remove the file from the website). To remove the file itself first delete the file in your working repository, and then use the cvs remove command to mark it for deletion. (Note, however, that with TortoiseCVS these two operations are merged into one, just select the file, right click and select Delete). Next use the cvs commit command on the file specifying in the message why the file is being deleted. The file will be removed immediately from your working repository and from the website at the next handoff.

Committing a file marked with cvs remove does not destroy the file's history. It simply adds a new revision, which is marked as "non-existent". The repository still has records of the file's prior contents, and can recall them as needed - for example, by cvs diff or cvs log.

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!

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!

Installing and using PuTTY

As stated above connection with the server is done using the ssh protocol. The recommended software to do this is PuTTY although there is other software that can be used.

Install PuTTY

Download PuTTY from the PuTTY download site. Choose Windows installer from the options offered.

Restart your machine (in order to get Pageant running in the background).

Generate key

To generate the correct key run PuTTYgen from the program menu.

Select SSH2-RSA and a key length of 1024 (should be the default).
Click Generate. Input randomness as directed.
Enter the passphrase (password) you want to use with this mechanism twice. Choose an secure password that only you will know, and if you write it down make sure it is secure.
Click on Save Public Key; this can be anywhere but typically in a folder called .ssh in <freebmd> (i.e. c:\freebmd\.ssh). The filename can be anything but conventionally it is yourname.pub
Click on Save Private Key; typically same place as public key and named yourname.ppk; you need to use this for input to Pageant.
Send your public key, yourname.pub, to . Do not send your private key (yourname.ppk) to Dave or to anyone else. Treat it as a password.
Dave will set up a login (referred to as username) for you on the FreeBMD development machine. You will receive an e-mail message from Dave notifying you of your login name, and password for trac.
It would be wise to ask Dave to set you up to be mailed with all CVS commits

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 Data

Auto login username username (your server username)

Now click on SSH

	Preferred SSH protocol version	2 only
	Encryption cyper selection policy	Ensure that 3DES is the top item in the box, using the Up/Down buttons as appropriate

Now click on the plus (+) next to SSH, then click on Auth

	Bypass authentication entirely	Unchecked
	Attempt authentication using Pageant	Checked
	Allow agent forwarding	Checked

Click on Session and type the name cvs in the Saved Sessions box and click on Save.

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 private key file (this will be cvs-home\.ssh\yourname.ppk) 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.

You can now run cvs to interact with the server as described previously.

You will need to run pageant and enter your passphrase every time you restart your machine or login to your machine. If you don't you will get the message "No supported authentication methods available".

Using DOS Commands

All of the CVS commands mentioned in this tutorial are executed at the command prompt in a DOS window. If you are unfamiliar with DOS you should find this section helpful:

The file system on any disk begins with the root (top-level) directory, represented as a backslash. Thus C:\ represents the root directory on the C: drive. Each additional nested directory can be represented as another element in the path, with a backslash used to separate each one. C:\Windows\System\Colour means that the Colour folder is in the System folder in the Windows folder on the C: drive.

To open a DOS window in Windows 98, click on Start - Programs - Ms-DOS Prompt. In Windows XP, Start - All Programs - Accessories - Command Prompt.

When you open a DOS window you should see a command prompt such as C:\>. The first letter indicates which drive is currently in use - the 'active' drive.

If you want to change to a different directory, say to the colour directory, you would type cd c:\system\colour and press 'Enter'. The command prompt will then change to c:\system\colour>, showing that you are now in the colour directory.

Note: File names for the CVS repository, on UNIX, are case sensitive. Therefore, to make things simple for yourself always treat the file names in CVS as case sensitive.

Environment Variables

Each time a DOS window is created an environment is provided to store information (variables) accessible to DOS commands and your applications. Whenever you use CVS the following environment variables have to be set:

set home=<freebmd>, e.g. set home=c:/freebmd (this lets CVS know that freebmd is the 'home' directory in which the files are to be stored). Note: The forward slashes are intentional.
Set cvs_rsh=plink.exe (this lets CVS know that you want to use PuTTY - to use a different ssh package change the value here).
Path=%path%;c:\program files\cvs (assuming you have put cvs.exe in c:\program files\cvs)
Path=%path%;c:\program files\PuTTY (assuming you have put the PuTTY executales in c:\program files\PuTTY)

In order that these environment variables will be set automatically for each DOS session you run they need to be set in the following way:

Right click on My Computer - Properties - Advanced - Environment variables - Environment variables for <username> - New.
Enter the variables in the top pane thus: HOME, CVS_RSH and PATH. (If there is already a PATH variable in the Environment variables for <username> box, click on it and use Edit. Add ";c:\program files\cvs" to the end of the value - don't forget the semi-colon.)

Windows 98 has a System Configuration Utility (\Windows\System\msconfig.exe), which allows you to set environment variables. Click on the Autoexec.bat tab and look for a 'PATH' command. If there is one, click on edit and add your PATH command to the end of the existing one. If you don't see a PATH command, click on new and add the command. Add the HOME and CVS_RSH variables here as well.

Installing CVS

Download the Windows client from http://ftp.gnu.org/non-gnu/cvs/binary/stable/x86-woe/, choosing the latest version. Extract the files from the zip file downloaded to c:\Program Files\cvs (or some other location of your choice - but the rest of the instructions assume you have chosen this location).

Populating your working copy of the repository

Before you can edit any files you need to download the source files into your working copy of the repository.

Open a DOS window and navigate to the 'Home' directory <freebmd>, e.g. cd c:\freebmd.
Download the source from the repository by typing the command:
cvs -d cvs:/home/cvs checkout UKGEN-FreeBMD

Note: cvs (as in cvs:/home...) is the PuTTY session name created for the purpose of using CVS as described here.
The next stage takes some time, and you may think nothing is happening. Be patient! There are a lot of files to download. Eventually the files in the repository will start to download into your home directory. The download will be complete when you are returned to the DOS command prompt.
During the download process a folder called UKDGEN-FreeBMD (or as appropriate for other projects) will be created inside the home directory, and will hold all the downloaded project files and folders.

FreeBMD Main Page

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