Subversion

Using the Elvis Subversion repository

This page aims to provide all the information necessary to access the Elvis SubVersion repository. Subversion is an alternative to CVS which we prefer. If you've never heard of CVS or Subversion then consult the http://en.wikipedia.org/wiki/Subversion_(software) fountain of knowledge.

Repository Structure

The Elvis repository is located at /vol/projects/elvis-svn. Each project has a top-level directory under this. For example, the "Lego Hypothesis" project is located in /vol/projects/elvis-svn/lego. Furthermore, each project directory is divided up into two main subdirectories:

  • '''/papers/''' contains research papers related to the project. Each has its own subdirectory and should be named using the first letters of Author's last name, Conference abbreviation and YEAR. For example, if myself (DavidPearce) and James Noble write a paper for the 2006 Aspect-Oriented Software Developers (AOSD) conference as part of the Lego Hypothesis project, then it goes into /lego/papers/PN-AOSD06/.
  • '''/tools/''' is used for holding all things related to whatever software tools/libraries are being developed as part of the project. Again, each should have its own appropriately named subdirectory. For example, if I've written a tool called "Squirrel" as part of the Lego Hypothesis project, then it goes into /lego/tools/Squirrel.

Accessing the Repository

There are numerous ways to access the subversion repository. As a start you can browse (but not modify) the repository via a web interface, http://www.elvis.ac.nz/viewcvs. Otherwise, the easiest thing to do is to simply use the "svn" command-line tool (see below). Other options are:

  • Subclipse - An Eclipse plugin (I haven't used this yet, so any feedback on this would be appreciated).
  • ToitoiseSVN - A windows client which integrates nicely into Windows Explorer.
  • ViewCVS - A Web-based SVN client. Note, we already have a ViewCVS client setup for the Elvis repository here.
  • JSVN - A Java SVN client.
  • JavaSVN - Yet another Java SVN client.
  • svnX - OS X open source GUI SVN client.

Subversion Command-Line Basics

I'll now go through some of the basic things you'll want to do, such as creating a new paper/project and updating it after changes. I'll keep things reasonably short and, for more information, you should refer to the Subversion Book.

Creating New Directory

Suppose we have a software tool called "Squirrel" and we wish to put this into the repository. Currently, the source code for "Squirrel" is in a local directory called "squirrel". The first thing to do is delete any temporary/unneeded files in squirrel to avoid them from being added as well. Then, I import the squirrel directory and all its contents into the elvis repository like so:
svn import squirrel file:///vol/projects/elvis-svn/qbd/tools/squirrel/trunk/

At this point, svn will promt you enter a log message. If it says you need to specify which editor to use, then edit the file ".subversion/config" from your home directory and set "editor-cmd" to whatever you use (I use vi). Or you can use the -m option and specify a message, i.e. -m "adding squirrel source to version control". Once you've entered the log message you'll see something like this:

Adding squirrel/test.java
Adding (bin) squirrel/test.class
Adding squirrel/lib
Adding (bin) squirrel/lib/squirrel.jar
Adding squirrel/bin
Adding squirrel/bin/squirrel
Adding squirrel/data
Adding squirrel/data/results
Adding squirrel/data/results/26072005-14:28:57
Adding squirrel/data/results/26072005-14:28:57/results.ps
Adding squirrel/data/results/26072005-14:28:57/results.dat
Adding squirrel/data/results/26072005-14:28:57/gnuplot.script
Adding squirrel/data/results/26072005-15:32:44
Adding squirrel/data/results/26072005-15:32:44/results.dat
Adding squirrel/data/results/26072005-15:52:19
Adding squirrel/data/results/26072005-15:52:19/results.dat
Adding squirrel/data/gen.pl

This means the files have been uploaded to the destination directory (/vol/projects/elvis-svn/qbd/tools/squirrel/trunk/ in this case, where qbd is the "Query-Based Debugging project). Note, the destination is "squirrel/trunk", rather than just "squirrel". The "/trunk/" subdirectory holds the main "trunk" of the development tree. Other common subdirectories to use are "/tags/" (to store released versions) and "/branches/" (for forks in the development tree).

At this stage, I have created a new directory within the repository. However, my original "squirrel" folder is not yet ready to be used --- I must now "check out" the directory from the repository to my local filesystem.

Checking out an Existing Directory

To get a local copy of the squirrel directory in the repository, I can use the following command:

svn checkout file:///vol/projects/elvis-svn/qbd/tools/squirrel/trunk/ squirrel-svn

This puts the contents of "squirrel/trunk" into a directory called "squirrel-svn" on my local filesystem. Now, I can work on the tool and subversion will keep track of what has changed. When I've finished, I must "commit" my changes for them to be reflected in the repository.

Checking Status

Suppose I've been working on my squirrel tool and I want to see what files have been changed:

> svn status
? anothertest.java
M test.java
! test.class

The output shows us what has changed. "?" means subversion doesn't know anything about this file. This has happened because I created the file in my editor and haven't told subversion about it yet. I can do this with "svn add anothertest.java" which will add that file to the repository. The "M" indicates the file test.java has been changed. To see what has changed (in case I forgot), I can do "svn diff test.java". Finally, "!" means the file has been deleted locally without telling subversion. This has happened because I delete the file using "rm". If I want the file to be deleted from the repository then I need to do "svn rm test.class".

Committing Changes

To commit any changes I've made, I simply use the following command:

svn commit
or
svn commit -m "add a useful message here"

As before, svn will ask for me to enter a log message. This message will be recorded with each of the files that changes, allowing me to look back in the future and see what was changed, why it was changed and by whom. '''Please make every effort to write useful log messages --- that way, people will be able to see what you've done and why'''.

Updating Your Copy

When two or more people are working on the same directory, subversion does not automatically update their individual copies with changes made by others. This is because the changes may conflict or break a local copy in some other way. To update your local copy to include all changes made by others , use "svn update".

A problem can arise when two people modify the same file --- this is called a conflict. The best advice is to try and avoid getting into this situation in the first place. For example, if you're writing a paper then break it up into separate files for each section, rather than having just one big file. That way, people can be working on different sections at the same time without any conflicts. But, if you do end up with a conflict, then you'd better read the [http://svnbook.red-bean.com/ Subversion Book], as I'm too lazy to cover it here!

Remote Access

One final thing worth mentioning, is that it's possible to use subversion remotely via SSH. This doesn't need anything special setting up (e.g. a subversion server), as it just logs in via SSH and then runs the commands as you would over a terminal. To do this, just specify the URL for the repository with something like
  • svn+ssh://circa.ecs.vuw.ac.nz:/vol/projects/elvis-svn/
  • e.g. svn co svn+ssh://alex@circa.ecs.vuw.ac.nz/vol/projects/elvis-svn/alex/papers/oopsla2006 oopsla2006
  • e.g. svn import oopsla2006 svn+ssh://alex@circa.ecs.vuw.ac.nz/vol/projects/elvis-svn/alex/papers/oopsla2006

When working remotely, it can be a real pain to keep typing in your SSH password all the time! To avoid this, you need to use an SSH agent. That way, you enter your password once and only once. You might find [http://mah.everybody.org/docs/ssh this page] helpful with setting this up (If anyone knows of a better discussion, please let me know).

Subversion and Eclipse

Installation

The Subclipse Plugin provides SVN support for the Eclipse workspace. It's installed like any other plugin - note that on the MCS system you will need to create a separate directory under your home directory to store additional Eclipse plugins that you want to install on your own user account. To set this up, you need to configure a "Local Site" for plugins:
  1. Select from the menu: Help > Software Updates > Find and install ...
  2. Select "Search for new features to install"
  3. Select "New Local Site"
  4. Enter the path to your plugin directory (probably called something like /u/students/yourname/bin/eclipse/)
  5. Select the further "Yes"/"OK"/"Approve"/etc buttons to complete

Once the Subclipse plugin is installed, you need to configure a repository location by right clicking in the SVN Repository view, and selecting:

New > Repository Location...

The SVN root URL should look like:

svn+ssh://circa.ecs.vuw.ac.nz/vol/projects/elvis-svn

Using the Repository Viewer

The two main features of Subclipse are the ''SVN Repository Exploring perspective'' and the additional ''Team'' functionality added to the context menu of the Package Explorer and Navigator view.

Once you have set up a repository location, you can link it to an active project in the workspace, and access various SVN commands by right clicking on a directory or file in the Package Explorer etc, and selecting the command under the ''Team'' menu.

Tutorial

There is a tutorial on how to use Subversion with the Subclipse plugin for Eclipse , see Using Subversion with Eclipse.

Subversion and Email

There is an auto-emailer wedge installed in the elvis-svn server. To activiate, do something like this from the top level working directory of your project, and then commit.

svn propset notify "rashina stuart kjx"  .
svn commit -m "set notify property to email us"

Note the dot "." at the end of the first line