How-to use Subversion

Subversion is a free/open source version control system (like CVS). That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of "time machine".

THE reference for subversion is freely available online at http://svnbook.red-bean.com/. This section will concentrate on the basis and the interaction with Gforge @ uni.lu, more precisely:

Subversion is available on every platforms as it can be seen on the official website. If you are using Windows, please follow our instructions in the corresponding section.

Basic command-lines on Linux/BSD/Mac

If you have never used svn before, then you can start using it right away as explained in the "SCM" tab of your project (this acronym stands for Source Code Management). To access the SCM page of the project myproject, go to your project page, http://gforge.uni.lu/projects/myproject, and click on the "SCM" tab located in the top right of the page. If your login on Gforge @ uni.lu is mylogin, then the initial checkout of your repository (i.e a local copy of the last version of the repository) is done through:

svn checkout svn+ssh://mylogin@svn.gforge.uni.lu/svn/myproject

This command will create a local directory named myproject. Once you are inside it (cd myproject), the typical command you'll need are described below:

  • add the file or directory toto to the repository:
    svn add toto
    

Note that the wildcard * can be used (for instance, you can use svn add *.c to add all C files to the repository).

  • check the status of your local copy with the last version of the repository (to see for potential conflicts):

    svn status
    
  • update your local copy of the repository with the last version:

    svn update
    
  • commit your local modifications on the repository:

    svn commit
    
  • rename a file or a directory from old to new:

    svn mv old new
    
  • delete a file or a directory:

    svn rm myfile
    
  • In all case, you can get help on a given command cmd by issuing

    svn help cmd
    

Other subversion commands can be useful for you:

  • svn info svn+ssh://mylogin@svn.gforge.uni.lu/svn/myproject : get various info on the repository myproject
  • svn diff : check the difference between the local and the remote copy

As for structuring the repository, you may be interested in reading the Subversion best practices.

Solving conflicts

In the result of svn status and svn update, you will obtain a status code for each element. Here are a few examples of the most common status codes that svn status can return. (Note that the text following # is not actually printed by svn status.)

?       scratch.c           # file is not under version control
A       stuff/loot/bloo.h   # file is scheduled for addition
C       stuff/loot/lump.c   # file has textual conflicts from an update
D       stuff/fish.c        # file is scheduled for deletion
M       bar.c               # the content in bar.c has local modifications

If you have a conflict on one file, there are three ways to solve them. See here for more details.

Configuring TortoiseSVN for Windows users

This section is directed to windows users. Before you start, be sure you already loaded your ssh key with pageant even if you have not set a passphrase on your SSH key. Instructions to do so are mentioned here.

TortoiseSVN lets you work with files under SVN version control directly from Windows Explorer. You can download it from the TortoiseSVN web site. Once TortoiseSVN is installed, you have to restart your computer.
TortoiseSVN is directly available by right clicking on files and folders within Windows Explorer.

TortoiseSVN

To configure our SVN repository, we click on the SVN checkout menu item:

TortoiseSVN

Here, you have to fill in the URL of your SVN repository. The standard URL to access your project on Gforge @ uni.lu is svn+ssh://<your_login>@svn.gforge.uni.lu/svn/<your_project>

Just replace by your Gforge login and by the unix name of your project. On your first connection to svn.gforge.uni.lu, you will see the following message :

TortoiseSVN

This message is displayed because the server key (Gforge key) is not known. Click Yes to add the key of this site to the list of pairs of known keys/hosts. Then, the checkout is done:

TortoiseSVN

Configuring the Access Control on a project repository

Each repository comes with its configuration files available on Gforge @ uni.lu in /svn/yourproject/config/. This directory contains three files:

  1. svnserve.conf: the main configuration file
  2. authz: contains the Access Control List for a path-based authorization
  3. passwd: forget it ;)

Those files can be modified by the admin(s) of the project.

If you want to activate a path-based authorisation, you have to connect to the gforge by SSH (using ssh yourlogin@gforge.uni.lu - this supposes of course that you have already configured your SSH connection) and edit the file (with vim or nano), and uncomment the following line:

#authz-db = authz

This activates the authz file that you now have to edit to configure the access control on a given subdirectory. Here is a small example, please read the reference book for more details.

Assume that your repository has the following structure:

trunk/
trunk/src/
trunk/doc/
trunk/www/

In the authz, one section is dedicated to the definition of groups from members of the project.

[groups]
admin       = yourlogin
src_devel   = @admin, toto, tata
doc_writers = @admin, tutu

Note: as in the example above, a group can be used in the definition of a group.

Once the groups are defined, you can specified for each directory the access rights:

[/]
*      = r
@admin = rw

[/trunk/src]
@src_devel   = rw
*            =

[/trunk/doc]
@doc_readers = rw

[/trunk/www]
@doc_writers = rw
* =

Automatically send mail on commits

Using the note of post-hook scripts in subversion (see the official description), it is possible to specify some scripts or commands to be launched after each sucessfull commit.

Your repository on Gforge @ uni.lu comes with a template for this script, just issue the following commands to activate it ($ stands for the prompt and is not part of the command of course):

    $ ssh yourlogin@gforge.uni.lu
    $ cd /svn/yourproject/hook
    $ ls -l
    -rwxrwxr-x 1 104 yourproject 2.1K Sep 23 12:21 post-commit.tmpl
    -rw-rw-r-- 1 104 yourproject 1.7K Mar 12  2008 post-lock.tmpl
    -rw-rw-r-- 1 104 yourproject 2.3K Mar 12  2008 post-revprop-change.tmpl
    -rw-rw-r-- 1 104 yourproject 1.6K Mar 12  2008 post-unlock.tmpl
    -rw-rw-r-- 1 104 yourproject 2.9K Mar 12  2008 pre-commit.tmpl
    -rw-rw-r-- 1 104 yourproject 2.0K Mar 12  2008 pre-lock.tmpl
    -rw-rw-r-- 1 104 yourproject 2.7K Mar 12  2008 pre-revprop-change.tmpl
    -rw-rw-r-- 1 104 yourproject 2.0K Mar 12  2008 pre-unlock.tmpl
    -rw-rw-r-- 1 104 yourproject 2.1K Mar 12  2008 start-commit.tmpl
    $ cp post-commit.tmpl post-commit

Note: you can have a local copy of this script from the repository of the helpdesk project which you can retreive anonymously by:

    svn checkout svn://svn.gforge.uni.lu/svn/helpdesk

The post-commit script is located in /trunk/hooks/.

For those who are interested, here is the content of a post-commit script to automatically send a mail to the mailing list myproject-commits@lists.gforge.uni.lu on successful commits (you can copy-paste this code directly without modification):

    # POST-COMMIT HOOK
    #
    # The post-commit hook is invoked after a commit.  Subversion runs this hook by invoking
    # a program named 'post-commit' with the following ordered arguments:
    #   [1] REPOS-PATH   (the path to this repository)
    #   [2] REV          (the number of the revision just committed)
    #
    REPOS="$1"
    REV="$2"
    PROJECT=`basename $REPOS`

    # format: commit-email.pl [-s subject_prefix] [-r reply-to] [-h hostname] repos rev address
    /usr/share/subversion/hook-scripts/commit-email.pl \
                             -r "${PROJECT}-commits@lists.gforge.uni.lu" \
                             -h users.gforge.uni.lu                      \
                             ${REPOS} ${REV} "${PROJECT}-commits@lists.gforge.uni.lu"