Subversion for version control

From NA-Wiki

Jump to: navigation, search

Version control systems are designed to help keep track of documents that are frequently revised by one or many authors. This is typically the case when programming, and when producing a manuscript for a scientific publication. Using a version control system makes your life easier when

  • there are more than one person working on the project
  • you want to keep old versions of the code for future reference (and reversion) but find it silly to manually create directories like ./code_v_0.1_backup_date.
  • you are writing a manuscript for a scientific publication together with collaborators
  • you want to share the code with someone (i.e. your professor). You will want to share the latest working version, and not the messy directory that contains the current version of the code (which may not always work) along with all the junk that accumulates when you code, run, and test.

In fact, a version control system will make it much more likely that you manage to maintain control of the code. Version control makes you a better programmer -- and it's not hard at all to use! This is a simple tutorial on how to get started with Subversion (SVN), a modern version control system. Visit the official homepage.



There is a phenomenal book on SVN freely available online, here. You may read it and skip this tutorial completely (but the tutorial is not 300 pages). Either way, you will want to turn to it as a reference for more involved stuff. Also, the first 40 pages give a very nice introduction.

Main concepts: Repository and working copy

In SVN the repository is a database that resides somewhere in the file system. It contains the program and a complete history of all changes that has been made to the code since it was put under version control. You will never make changes to the code by editing in the repository.

All work happens in a working copy. One checks out the code from the repository into another directory (by extracting the latest revision from the repository database and copying it). Code development happens on the working copy and then the changes are pushed onto the repository as the developer feels the new code is working as it should.

Create the repository

First choose a place to put the repository. A good choice is ~/svnroot/. To create a the repository for a new project do

$ svnadmin create ~/svnroot/project_name

Check out a working copy

Go to the place in the file system where you write code, such as ~/workspace/. To check out the newly created repository do

user@host:~/workspace/ $ svn checkout file://$HOME/svnroot/project_name

It should say the it has checked out revision 0. Now you have a working copy in the directory project_name. That folder is, however, empty (except for a directory .svn which we do not care about) since the project contains no code yet.

Add files

Go to the working copy. Put some code in this directory, say hello.c and Makefile. Now put these files under version control by

$ svn add hello.c Makefile
A         hello.c
A         Makefile

The A above indicates "add", i.e. those files will be added to the repository when the changes are committed.

Committing changes

The final step is to commit the changes made (i.e. that two files have been added). The command is

$ svn commit -m "Added files hello.c and Makefile"
Adding         hello.c
Adding         Makefile
Transmitting file data ........................
Committed revision 1.

Tools for common tasks

Always do svn help when you don't remember a command. Here are the most useful ones:

  • svn status shows the status of the working copy. If we did this after adding the files above SVN would tell you that these two files are to be added to the repository (the A in the left column). File may otherwise be modified (M), deleted (D) or not under version control (?).
    • svn status -u: Stat against latest revision in the repository
  • svn update updates against the latest revision in the repository.
  • svn diff "file" runs diff between this file and the one checked out from the repository. This is the convenient way to check what changes you have made to a particular file.
    • svn diff -r HEAD: runs diff against the lates revision on the repository.

Resurrecting a file from an older revision

Say that the file foo.c has been removed, but now turns out to be interesting again. How to get it back? Well first we have to know in which revision it existed. We use the copy command in SVN:

svn cp -r 100 file://$HOME/svnroot/repository_name/foo.c foo_old.c

where the flag -r 100 specifies that we want the version of the file that existed in revision 100. Note that this works equally well for reverting a file that exists in the repository back to a previous revision.

Some things NOT to do

  • Do not move or remove files that are under version control using mv or rm, since this will break the version control of the code. Use svn move and svn rm instead. Note that files that have been removed can be reverted from earlier revisions.
  • Do not commit code to the repository that does not work. The repository should contain the latest working copy (in the sense that it runs at least). Fixing bugs, adding features etc, however is part of the development cycle (i.e. the code that is committed doesn't need to be "final").

RapidSVN - A GUI for SVN operations

Subversion has many more features than what has been presented here. And in certain circumstances problems occur. Two things to remember when things look complicated are

  • Subversion has features that handle most conceivable problems that can occur in a development project (it's mostly a question of finding help).
  • The on-line guide has most answers (link above).

Still, it can be comforting and convenient to have a GUI that gives an overview over repositories, working copies, patches and change-sets. Support for SVN is embedded in certain IDEs, but there is a stand-alone tool called RapidSVN that gets the complicated jobs done.

Access via SSH

To checkout a project, use the svn+ssh protocol:

$ svn checkout svn+ssh://username@host/path

Then use svn as usual. You will be prompted by ssh for your password when you request operations on the repository.

Information for NA group members

  • There is a server which has SVN running:
  • Create a repository on your AFS volume
  • Set permissions for others (i.e. collaborators) in that directory using the fs command, like 'fs setacl <path> <user> <acl> '. There is a utility cleed fsr to set permissions recursively in a file tree. If that one is not available it MAY be safe to use
> find . -type d -exec fs sa {} -acl <username> <rlidwka> \; -print

Only use this if you are certain that the particular directory does not contain links to other places in the file system!

  • From your favorite SVN client, or command line, check out a working copy via the SSH layer from na37:
$ svn checkout svn+ssh://
  • If you put the repository in a directory called svnroot in your home folder, and the name of the project is proj_name, the command should be
$ svn checkout svn+ssh://$HOME/svnroot/proj_name

Common error message(s)

svn: Unable to open repository 'file:/// <path to repository> '
svn: Berkeley DB error for filesystem ' <path to repository> /db' while opening environment:

svn: Cannot allocate memory
svn: bdb: unable to allocate memory for mutex; resize mutex region

This is not an indication that the repository is corrupted or that any data is lost. The official HOWTO (and explanation) is here. The guist of it is to run

 svnadmin recover <path to repository>

Warning: You can seriously corrupt your repository if you run recover and another process accesses the repository. Check the official HOWTO for important details.

Personal tools