FreeBMDFreeBMD What is CVS?

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:

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).
  1. 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.
  2. 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.
  3. You test and tweak your latest changes in your own workspace to make sure these work without breaking or corrupting the overall project.
  4. 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:

Having acquired and installed the above you will then need to do the following: 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.

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:

cvs commit
Commit your changes into the repository (it is good practice to first run cvs diff (see below) and check that the changes being committed are what you intended). 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). Save the changes and close the file to complete the commit. 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:
cvs editors
Find out who is working on a file (Co-operative mode only).
cvs edit
Register that you will be editing a file (Co-operative mode only).
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
Find 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>

cd UKGEN-FreeBMD
cvs update -AdP

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 create the file in your working copy of the repository and then 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, unless the binary file is small, is to make the first commit a dummy file and then commit the real file as a second commit.

Creating a new directory

To add a directory, first create it in your working copy of the repository and then do a cvs add. Unlike for a file you do not do a commit ... the directory is added to repository immediately. If you need to add a directory at the top level of the UKGEN-FreeBMD repository it must be added to the conf/webserv_directories file otherwise it will not be deployed in the handoff.

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.

Abandoning local edits

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

Reverting to a previous version

Sometimes you will want to revert the source of a module back to a previous revision, for example when changes have been committed that are later found to be not required. There is no revert command in cvs but it is reasonably simple to do a reversion on a single file. First you need to find the current revision (referred to as currentrev below) which you can do using the following:
cvs status filename
You can then feed the value of currentrev found into the following in order to revert to the revision oldrev:
cvs update filename
cvs update -j currentrev -j oldrev filename
cvs commit filename
cvs tag -F BMD_LIVE filename
The second update above merges the changes between currentrev and oldrev (the one you want to go back to) into your working directory version which means that the version in your working directory becomes the same as oldrev.

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.

Create a PuTTY saved session

Run putty and set up the following parameters (in the Session section)
 Host Nametest.freebmd.org.uk
 Port22
 Connection typeSSH
 Saved sessions (box)cvs

Expand the Connection settings by clicking on the "+" next to "Connection" (unless already expanded) and then click on Data

 Auto login usernameusername (your server username which is likely to be different from your FreeBMD username)

Now click on SSH (under Connection) and ensure the following setting

 SSH protocol version2

Now expand the SSH section by clicking on the plus (+) next to "SSH", then click on Auth and ensure the following settings

 Bypass authentication entirelyUnchecked
 Attempt authentication using PageantChecked
 Allow agent forwardingChecked

Click on Session and then 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: Whilst you could do this each time you used CVS it is much more convenient to have them set automatically for each DOS session you run and this can be done in the following way: 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.
  1. Open a DOS window and navigate to the 'Home' directory <freebmd>, e.g. cd c:\freebmd.
  2. 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.
  3. 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.
  4. 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.

TortoiseCVS

One client that has been used to access CVS is TortoiseCVS. However, this software appears to be no longer under development or support. Furthermore, since the installation of new versions of the secure protocol SSH on the servers, access to CVS from TortoiseCVS has stopped working. A workaround for this is as follows:
  1. create a saved session cvs in PuTTY as described above (unless you already have such a saved session)
  2. set up TortoiseCVS Preferences to use this saved session (by convention this is called 'cvs') , that is
    SSH application (:ext: only):  set to point to PuTTY's plink.exe e.g. C:\Program Files (x86)\PuTTY\plink.exe
    SSH parameters (:ext: only):-load cvs
    SSH cvs server (:ext: and :ssh:):cvs
  3. either edit each Root file in the CVS directory in each folder of your repository to use :ext: instead of :ssh: or (probably the easier option) download a new version of the repository either as described above but using a new "Home" folder or using TortoiseCVS as follows:
    1. Create a new 'Home' folder in Windows Explorer
    2. Right click on the folder, select CVS -> Make New Module
    3. Enter :ext:username@test.freebmd.org.uk:/home/cvs into CVSROOT on TortoiseCVS Make New Module Screen (substitute your server username)
    4. Click Fetch list to get a list of modules
    5. Select UKGEN-FreeBMD module
    6. Click OK - this will download a copy of the repository to your PC.

FreeBMD Main Page


Search engine, layout and database Copyright © 1998-2022 Free UK Genealogy CIO, a charity registered in England and Wales, Number 1167484.
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


Explore FreeBMD