Tomcat support and managed J2EE - servlet/jsp/ejb

CVS/Subversion Primer

Who should read this

This document is targeted at the developer who needs a 10 minute primer into getting started with CVS/SVN. For comprehensive details of CVS please refer to the canonical versions CVS/SVN. Note: We only cover SSH remote access as this is the only way of working with CVS/SVN with Name On The Net accounts. Subversion (SVN) has become increasingly popular as it was designed as improvement for CVS, however we discuss these in context with each other as from a high level they are very similar and the concepts behind them are strongly related.

Overview

CVS and SVN are used in software development as versioning tools which facilitates code being concurrently (note the Concurrent in CVS) modified by multiple programmers. Without the use of some form of control, chaos would surely ensue as developers overrode each others work. In addition to being a tool which facilitates numerous programmers working on a software project, using a revision control system is still very useful when projects are being maintained/developed by a single programmer.

The concept behind version control is simple: take regular snapshots of your code and annotate the changes made with comments. Through this simple action a wide array of opportunities arise, you now have a facility to rollback your code, compare your current code with historic versions, and view the genesis of your software by reading the comments. More advanced uses include having separate development branches for your project. Full details are available in the manuals available from the links above.

Used properly version control is a incredibly powerful (and in some cases indispensible) tool, most of the major open source software projects (Linux's recent departure making it a notable exception) use CVS or SVN. Inexperience with a version control can and will become a barrier for the developer who wishes to contribute in open source projects; something of an issue recently highlighted on the struts developer mailing list.

Setting up the repository

Before code can be imported into a CVS or SVN system a repository must be created, a repository is the area of the filesystem where code under the control of the respective version control is located.

CVS repository creation

# repository's location set via command line switch

shell$ cvs -d /cvsweb init

# repository's location set using a CVSROOT environment variable

bash$ export CVSROOT=/cvsweb

csh$ setenv CVSROOT /cvsweb

shell$ cvs init

Note: All future CVS examples assume you have CVSROOT defined as an environment variable Note: Also set the EDITOR environment variable to your favourite editor

SVN repository creation

Unlike CVS which has a single command - cvs - to carry out tasks, SVN comes with utilities which serve separate purposes, the svnadmin utility is used to perform administration tasks. To create the SVN repository issue this command:

svnadmin create /your/svn/location

Importing your project into the repository

Once the repository has been created the next logical step is to import a project into the version control system.

Importing a project - CVS

'cd' into the directory of the project that will be imported into CVS, for example if the project is within the /usr/web/site directory then "cd /usr/web/site" will place you into the directory. Issuing the following command will start the import process

shell$ cvs import repository vendor-tag release-tags

Notes on the command line parameters:

repository - The name of this project (important as this will be the name you use for future cvs operations)
vendor-tag - Your name or the name of your company
release-tags - Something useful which describes this import which you can look back for future reference

CVS will automatically open an editor which you can use to comment on the import.

*Developers who work with compiled languages will probably not want to import compiled objects - Details of how to exclude them can be found here

Importing a project - SVN

Importing the project when using SVN is very similar to CVS,

shell$ svnadmin import /usr/local/project file:///your/svn/location/project

Unlike CVS, SVN provides an option of specifying where the project should be found as opposed to CVS where it assumes that the working directory is the project to be imported. Like CVS, SVN prompts for comments during this initial import phase.

Working with your project

Once a project has been imported into the version control system it needs to be 'checked out', the source directory used during the import stage has not been modified. The process of checking a project out is fundamental to version control systems, the concept is that each user has a 'working copy' which has been 'checked out' which they work with until a time comes when they feel they can commit their changes whereby the changes made are then available to the participants of the version control system.

Checking out a project - CVS

To check out a project using use the following command:

shell$ cvs co repository

The repository name corresponds to the repository used when the import was done.

Checking out a project - SVN

Checking out a project with SVN is similar to CVS although it is more customary to specify the location of the repository (as opposed to have defined the CVSROOT environmental variable with CVS).

shell$ svn co file:///usr/local/svn/repository

You will now have a directory called 'repository' which contains the project imported earlier. The files and directory layout will be similar to the project imported although both SVN and CVS create a series of directories (.svn and CVS) respectively which are known as 'administrative areas'. These are used internally and can be safely ignored. The 'working copy' can now be worked on until some point where changes made are ready to commit to the version control system. Identifying the difference(s) between the working copy and the repository can be achieved by using the diff command, i.e. cvs diff [filename] (or svn diff). There are a number of optional parameters which can be given with diff command, please visit the relevant documentation for full details.

Committing changes - CVS

shell$ cvs commit

CVS will recursively scan directories identifying where files have been updated since checked out (i.e. differ from those in the repository) and prompt you for comments (in your favourite editor: see above

Committing changes - SVN

shell$ svn commit

In identical fashion to CVS, SVN will recursively scan for differences between the working copy and the repository and then prompt for comments.

Apart from importing, viewing the differences between the working copy and the repository (i.e. changes made since the check out) and committing this there are a number of other common commands.

Useful CVS commands

cvs invoked with a --help-options switch provides a listing of modes of operation. Popular modes are:

status - The status of source files, have they been modified since checkout, etc
history - The history of source files, with comments provided when committed.
add - Add a file into CVS control, commit doesn't automatically (as you may expect) do this for you
remove - Remove a file from CVS control

Useful SVN commands

svn invoked with a help parameter, i.e. 'svn help' lists the available operations, the most useful are:

svn help [operation] - Provides a brief explanation and usage notes of the operation
svn status - Provides high level detail of differences between the working copy and the repository
svn revert [file] - Reverts back to the copy in the repository, useful to rollback changes
svn diff [optional file] - Shows the actual diff between files in the working copy and repository

Web developer notes

Java developers may instantly spot that .class files are imported which may be something that is certainly not wante. Both SVN and CVS have a mechanism where files can be excluded from version control. During the import process CVS scans for files called .cvsignore, and if found scans it for file patterns to be ignored. CVS has a global exclude file option which for brevity are now covered here, details can be found in the cvs manual. SVN has a similar mechanism, the most simple method is to edit the $HOME/.subversion/config file and modify the global-ignores field.

Remotely accessing a repository

One of the features that makes CVS and SVN so powerful is that they can be remotely accessed, which has been so fundamental to the success of the open source software movement where developers in disparate locations can freely and easily contribute to projects. For security concerns we only discuss SSH access options, CVS has a pserver mode but is inherently insecure and subject to numerous security warnings. SVN has a number of other remote access options, including DAV although only the SSH mode is covered here.

CVS remote access

To access a remote repository using CVS a modified CVSROOT must be specified: ':ext:username@hostname:/cvsroot'. To connect using SSH the CVS_RSH environment variable must be defined as 'ssh'. An example session which goes through the process of creating the repository, adding a project and remotely checking it out can see seen below:


 user@server:~$ cvs -d /cvsroot init
 user@server:~$ mkdir myproj
 user@server:~$ cd myproj
 user@server:~$ vi source.c
 user@server:~$ cvs -d /cvsroot myproj mycompany projectnotes import
 user@server:~$ exit

 user@home:~$ export CVSROOT=:rsh:user@server:/cvsroot
 user@home:~$ export CVS_RSH=ssh
 user@home:~$ cvs co myproj
 Password:
 cvs checkout: Updating myproj
 user@home:~$ cd myproj
 user@home:~$ vi source.c

SVN remote access

Accessing a SVN repository using SSH simply requires a slightly modified repository path that than which would be used for local access, for example: svn co svn+ssh://server/home/user/svn myproj would attempt to checkout myproj from the server 'server'. This is the only difference in working with the repository locally.

Document Version: 1.1

Date: 19/08/2006