Just Enough CVS - A Guide for Novell Forge Users
Novell Cool Solutions: Feature
By Simon Nattrass
Digg This -
Posted: 14 Jan 2004
Novell Forge (http://forge.novell.com) uses the Concurrent Versions System (CVS) at the "back-end" for versioning and storage of the Open Source projects it hosts.
This guide is intended as a simple introduction to daily use of CVS and the associated tools in the context of Novell Forge. It is not intended as a guide for CVS outside this use; please see the "official" manual by Per Cederqvist et al for more information.
What is CVS?
CVS is a version control system. Using it, you can record the history of your source files.
CVS is configured to manage one or more repositories, and each repository holds a collection of modules. A module is a set of files and directories which are under version control.
Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get (checkout) your own copy of the files into a working directory, and then work on that copy. When you've finished a set of changes, you check (or commit) them back into the repository. The repository then contains the changes which you have made, as well as recording exactly what you changed, when you changed it, and other such information.
CVS Components and Tools
CVS software consists of two components - the server piece which manages the repositories on the server machine, and the client piece which is responsible for the synchronization between the files in the (remote) repository and those in the working directory. When working with Novell Forge the client piece is only of real interest since the server component is "hidden" behind the site. Typically CVS clients are command line based, however recent developments have produced Open Source GUI front-ends, such a WinCVS and TortoiseCVS on the Windows platform. In this discussion we will focus on the use of TortoiseCVS.
As mentioned earlier CVS adheres to the client/server paradigm and communicates over several protocols (or locators) each with their own benefits (and drawbacks). Popular locators are: Local, External (or Secure Shell or SSH), Password Server, GSS-API server and Kerberos Server.
Novell Forge is configured to use the External/Secure Shell (SSH) protocol (:ext:)
What is Novell Forge?
Novell Forge is an Open Source software development web site geared towards Novell developers, providing free hosting to projects. The mission of Novell Forge is to enrich the Open Source and Novell Developer community by providing a centralized place for Open Source developers to control and manage Open Source software development.
CVS Services on Novell Forge
Each project hosted on Novell Forge is provided with their own CVS repository to aid in further development of your project. Developers on your project are automatically granted write access to your project CVS repository via SSH.
Uploading (importing) Files to a Project
Once a project is created via the site a user can then create a module in the associated repository. Usually this is done from an existing directory structure on the users' (client) machine, this process is known as importing a module. Below is an example of this operation using TortoiseCVS.
Making a new module from a directory on the local machine
In order for the CVS client to communicate with the server machine it needs to know the following details:
- protocol (Secure Shell or :ext: for Novell Forge)
- server (forgecvs1.novell.com)
- repository directory (/cvsroot/<project name>)
- user name
- module name
The concatenation of the first four items is know as the CVSROOT.
CVSROOT = <protocol><user name>@<server>:<repository directory>
Specifying CVSROOT as it's sub parameters
Having imported a module into the project repository TortoiseCVS will overlay the folder icon in Windows Explorer to represent an 'up to date' (in synch) folder with the repository.
Note: the overlay icon differs in the versions and configuration of TortoiseCVS.
The module showing that it's up to date with the repository
Although the module is now imported to the repository, it does not contain any of the contents of the working directory. Fortunately we easily can add these contents as follows:
Any changes made to the working directory, including changes to files or directory contents show up as out of synch with the module in the repository. To synchronize these changes with the repository we perform a commit operation. In this case, although we have now added the files to the module to keep continuity with this change/commit procedure the files show up (in the working directory) as out of synch until we commit them.
This can be seen in Windows Explorer via the icon overlays provided by TortoiseCVS (again the particular icon differs with version and configuration).
Files are out of synch with the repository
Again we can easily commit the contents from the root of the working directory.
Committing the contents of the working directory
Specify which files we want to commit and offer a comment
After committing these additions we see that all the files are now in sync with the repository.
Files are now in synch with the repository
Downloading (checking out) Files from a Project
Once a project is created and the associated files are present in the repository a developer may wish to download the files and make contributions. The process of copying a module from the repository to a working directory is known as a checking out. This works in a similar manner to importing a module.
First choose a directory (on the client machine) to checkout the module to and right click in Explorer.
Checking out a module to a working directory
Since the client requires a connection with the CVS server, the CVSROOT needs to be specified again.
Specifying CVSROOT as it's sub parameters
Having checked out the module we now have a working copy again on the local file system, and we can continue to make changes and commit them as required.
Checked out and ready to go
Browsing the Repository
The contents of the repository may be examined from the Novell Forge site via the "Browse the CVS Tree" link for any project for which you are an administrator.
Below is an example for a project which Novell Forge hosts.
Browsing the associated CVS Repository of a Novell Forge Project
PKI, TortoiseCVS and Novell Forge
Originally, you may have noticed, when using CVS that you were required to enter your password every time you performed a CVS request. This annoyance has now been removed. On your personal page there is a new tab called "My Public Keys". This page allows you to upload your public keys. The keys will be stored on one of our servers so that you can authenticate to the CVS server without your password.
Setting up Key-based CVS access to forge.novell.com using TortoiseCVS and PuTTY
PuTTY is a free implementation of Telnet and SSH for Win32 platforms, along with an xterm terminal emulator.
Generate Public/Private Key Pair
- First download and install PuTTY.
- To generate your keys, run puttygen.exe from the PuTTY install directory.
- Ensure the type of key to generate is "SSH1 (RSA)", and the number of bits is 1024, then click the Generate button.
- Move your mouse around in the box to generate some randomness.
- When your key is generated, change the comment to
@forgecvs1.novell.com and set a passphrase. Remember this as if you forget it you will need to generate new keys, there is no passphrase recovery.
- Now save the private key somewhere on your local system.
Register Public Key with Novell Forge
- Copy the contents of the public key box to the clipboard, and then in a browser window go to http://forge.novell.com.
- Login and go to 'My Personal Page', then 'My Public Keys'.
- Paste the contents of your clipboard (your public key) into the public key box, then click Add.
Register Private Key on Local Machine
- Now run pageant.exe from the PuTTY install directory. This will put an icon in your system tray which is a small computer with a hat on.
- Right click on this icon and click 'Add Key'.
- Navigate to where you saved your private key and click Open. Enter your passphrase (the one you mustn't forget above), and hit 'OK'.
The public key you uploaded should be recognized within the hour. If the following still doesn't work after an hour, you've probably done something wrong.
- Open a command prompt and navigate to the PuTTY install directory and run the command:
plink.exe -v <your username>@forgecvs1.novell.com
- If anything is wrong (which you will know by the fact that it will ask for your password), chances are that your key isn't recognized yet. If all is ok, you will be returned directly to the command prompt without being asked for your password.
Configure TortoiseCVS to use PuTTY
- Right click on any file/directory in Windows Explorer, and go to CVS -> Preferences.
- Go to the SSH tab and browse to Plink.exe in your PuTTY install directory.
You should be able to use TortoiseCVS quite happily now without having to type in your password over and over again.
The only caveats here are that you will need to manually restart pageant.exe after each reboot unless you put it in your Startup folder. Also, you'll need to specify the name of your private key file on the command line, otherwise you'll have to right click and select 'add key' every time you reboot. If you start pageant with something similar to:
<PuTTY install dir>\pageant.exe <private key location>
–then you'll just need to enter the pass phrase for your private key once.
- CVS - http://ximbiot.com/cvs/manual/
- CVS Manual (Per Cederqvist et al) - http://ximbiot.com/cvs/manual
- TortoiseCVS - http://sourceforge.net/projects/tortoisecvs
- WinCVS - www.wincvs.org
- PuTTY - www.chiark.greenend.org.uk/~sgtatham/putty
- PuTTY configuration guide - Kevin James
Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions. www.webwiseone.com