CVS for Virtual Access

NOTE This section is obsolete as the active VAOS repository is now managed using the git distributed version control system. The old CVS archives are still available on sourceforge, but will not be updated.

Please see here for more details.

Introduction

This document may appear to be long, but it contains a complete script of how to set up and use CVS. It won’t take long to read, but I hope it will help you understand the basics of what CVS does, as well as how to set it up and use it.

CVS (Concurrent Version System) is a uniquely powerful tool for managing source code that is being developed by multiple programmers at multiple locations. It automatically takes care of keeping a history of every version of the code, merging changes made by different programmers, remembering exactly which version of each source file went to make up a release, and applying bug fixes made to earlier releases to the current development code.

A central repository of all versions of the code is kept on the SourceForge server, and can be read by anyone using anonymous CVS access, and updated by any authorised person using SSH access.

Developers use a CVS client on their machine to interact with the central server. A Microsoft Windows client called WinCvs is available, as are command-line tools for Windows and Unix, both called CVS. The clients talk to the server over a secure, authenticated, fully encrypted link using the SSH Secure Sockets tool.

Each developer checks out one or more copies of the code on to their own machine, using their preferred client. At any time the developer can ask the client to update their copy of the code with any changes that have been made to the code in the central repository. This works even if two programmers change the same source file at the same time – CVS will merge the changes. Only on the very rare occasions when two programmers change the exact same source line at the same time is there a problem, in which case CVS will place both changes into the local copy of the file, one after the other, with special markers to indicate what has happened, and warn the programmer to correct the problem by hand.

When the developer is happy that their changes are tested and working, they tell their client to commit the changes. The central repository is updated, and these changes will be sent to all the other programmers next time they update their versions.

Programmers can also tell CVS to add files to and remove files from a project. Removing a file does not delete the history of that file, it just means that file is no longer retrieved when a programmer asks for the current version.

When code is released, a tag is added to the central repository. This marks the current version of each file with a name, which can then be used later to retrieve that exact same set of source files (e.g. for bug fixing).

Installing WinCVS

The latest version of WinCvs can be obtained from http://cvsgui.sourceforge.net/download.html. The version you want is "WinCvs 1.3 *BETA* / Client + Local / Binaries", latest x86 version. Download the zip file, and unzip it somewhere. This will get you a directory called something like WinCvs13b10, with a setup executable in it. Run setup, and do a full installation.

The latest version is now well above 2 and I certainly recommend using it. It's a bit different to setup first as explained here, but works very well. (Kai)

When you run WinCvs, it will complain that you haven’t installed Python (which is used for WinCvs macros). Ignore this warning for now; macros are not needed for basic CVS operation.

Getting anonymous (read-only) access to the virtual-access CVS repository on SourceForge

First, get a CVS client. I recommend WinCVS. See [Installing WinCVS-] above.

Set the WinCvs CVSROOT to access the development server by choosing Admin|Preferences, General tab. Set the Authentication method to pserver, the path to /cvsroot/virtual-access, the host address to cvs.virtual-access.sourceforge.net, and the user name to anonymous.

You may also want to set your default viewer (in the WinCVS tab) to be your favourite text editor.

Choose (or create) a directory in which you will do your development. This will be your WinCvs Browse location (View|Browse location|Change). Initially your Browse location should be an empty directory (even if you already have a copy of the source somewhere else). You may have multiple versions of the source code if you wish, each in a separate browse location directory. WinCvs will automatically keep track of which version is in which directory, and commit any changes to the right one. You can save different settings for each browse location (View|Browse location|Save settings) if you find it necessary.

Now let’s get the source code. Choose Remote|Checkout module. Set Module name and path on the server to VA6. Make sure the local folder is set correctly, and press OK.

You should see progress messages in the bottom window, and CVS should get you the complete directory you asked for. Often, you get the message "(cvs.sourceforge.net):2401 failed: No connection could be made because the target machine actively refused it.". This is a "feature" of SourceForge when the servers are overloaded. You just need to try again later.

Getting read-write access to the virtual-access CVS repository on SourceForge

In order to get read-write access, you first have to have a SourceForge login id, and you then have to persuade the Virtual Access Foundation to give you read-write permission.

Then you need to install an SSH client. I recommend PuTTY, from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. The file you want is "A Windows-style installer (x86 only) for everything except PuTTYtel". This will get you an installer. Run it to install PuTTY. Now you need to generate a public/private key pair to authenticate your connections to the CVS server. Run PuTTYgen. You want to generate a SSH2 RSA key. Set the key comment to <your user name>@<your machine name> (e.g. [nikki@trumphurst.com-mailto:nikki@trumphurst.com]). Select all the text in the Public key for pasting box, and copy it to the clipboard (with ^C). Save the private key to C:Program FilesPuTTY, naming it id_rsa.PPK.

Start a text editor; paste your saved public key into it, and save it as C:\Program Files\PuTTY\authorized_keys.

Now you need to register your public key with the SourceForge server. Click "my sf.net", and choose the "Account Options" page. Scroll down to "Host Access Information", and click "Edit Keys". Paste your public key into the text box, and press the Update button. Note that the key may take up to 24 hours to register with SourceForge. Access via ssh will not work until then.

Now we need to tell PuTTY where we put the key file. Start PuTTY. On the configuration screen, click the SSH radio button. Move to the SSH page, and ensure Preferred SSH protocol version is set to 2. Move to the SSH/Auth page, and browse to your id_rsa.PPK public key file (in C:Program FilesPuTTY). Return to the Session page, Click Default Settings, then press the Save button.

Then, get a CVS client. I recommend WinCVS. See [Installing WinCVS-] above.

Set the WinCvs CVSROOT to access the development server by choosing Admin|Preferences, General tab. Set the Authentication method to ssh, the path to /cvsroot/virtual-access, the host address to cvs.virtual-access.sourceforge.net, and the user name to your SourceForge login id. Click the Settings button, tick if ssh is not on the PATH, and enter C:\Program Files\PuTTY\plink.exe underneath the tick box (On one machine, I got strange messages about C:Program is not a recognised command, putting in C:\Progra~1\PuTTY\plink.exe - the DOS16 version of the path name - fixed the problem).

In the same dialog, on the General tab, set your HOME directory to C:\Program Files\PuTTY. You may also want to set your default viewer to be your favourite text editor.

Choose (or create) a directory in which you will do your development. This will be your WinCvs Browse location (View|Browse location|Change). Initially your Browse location should be an empty directory (even if you already have a copy of the source somewhere else). You may have multiple versions of the source code if you wish, each in a separate browse location directory. WinCvs will automatically keep track of which version is in which directory, and commit any changes to the right one. You can save different settings for each browse location (View|Browse location|Save settings) if you find it necessary.

Now let’s get the source code. Choose Remote|Checkout module. Set Module name and path on the server to VA6. Make sure the local folder is set correctly, and press OK.

You should see progress messages in the bottom window, and CVS should get you the complete directory you asked for.

Every day use of CVS

Keeping your copy of the code up to date

Edit, compile and test your files in the normal way. If you suspect someone else has updated the server with some changes you need, select the module you want to update, and choose Modify|Update selectionYou should do this at regular intervals if others are working on the code. The easiest way is to update the top level directory (VA6), which will get everything you might need.

Checking the current status of your code

WinCVS shows the versions of all the files in your local copy, and which files you have modified. You can find out which files have changed in the master repository since you last did an update by doing Query|Query Update. This will list all the files which have changed, with a letter to indicate the kind of change (e.g. U = needs updating from the master, M = modified locally, ? = file CVS does not know about).

Updating the master repository

When you think an amendment is complete, choose Update|Commit. With each commit, you should fill in the log message with basic details of the changes you have made (e.g. Added ticket system - you can go into as much detail as you like, over as many lines as you like). Just like update, you can commit individual files, selected files, or whole directories (which includes their subdirectories by default). It is best to update your files before committing them; otherwise your commit may fail because someone else has already changed a file you are trying to commit. In any case, WinCvs or CVS will tell you what happened. Note that you should follow the VA convention of updating the ".history" and "build.h" files to reflect the changes you have made.

Adding and deleting files

If you have created a new file, click on the file in WinCvs, and choose Modify|Add Selection. This will tell CVS that the file should be added to the master repository next time you commit your changes. Make sure the file has the correct and appropriate header comment, including copyright information, etc.

To delete a file, click on the file in WinCvs, and choose Modify|Remove. In the same way, this will mark the file in the repository as removed in this version when you next commit your changes (it will be removed from your disk at that time, too). Anyone updating the current version will have that file deleted from their disk. Anyone checking it out won’t get that file. But people checking out an earlier version will get the earlier version of the file.

Note that there is no way of renaming files (except by someone who has direct access to the repository hacking it).

Comparing revisions

You can compare your current code with the latest version in the repository, or with an earlier version, or even compare two different versions in the repository using Query|diff selection. By default, the differences are shown in Unix diff format. If you are comparing a file (rather than a whole directory or project) can tell WinCvs to use a visual diff tool.

I use WinMerge from http://winmerge.sourceforge.net/, which will also happily compare files and/or directories on your hard disk. To tell WinCvs to use a visual diff program, choose Admin|Preferences, WinCvs tab, check the External diff program checkbox and enter the program name (in my case, C:Program FilesThingamahoochie SoftwareWinMergeWinMerge.exe).

I found that the downloadable binary version of WinMerge has a few bugs, but the development source has them fixed, so I use the development version. If you want a development binary, let me know and I’ll email it to you.

Further reading

All the documentation for WinCvs is available at http://cvsgui.sourceforge.net/download.html.

All the documentation for CVS is available at http://www.cvshome.org/docs/. The links page also lists other clients, and useful tools, including Microsoft Developer Studio integration.

The documentation for WinMerge is available at http://winmerge.sourceforge.net/.

 
devinfo/cvshowto.txt · Last modified: 02.01.2015 19:53 by daniel
 
Recent changes RSS feed Driven by DokuWiki