Introduction

The SPRAAk code base is stored in a single repository under the control of a vcs (version control system). This provides:

A single point where one can fetch the latest version of the code base.
The ability to track changes to the code base throughout the lifetime of the product.
The ability to revert to any previous versions of the code, e.g. if some changes give too much problems or seem a bad idea after the facts, of for debugging older releases.
The ability to label and reproduce previous released versions of the product.

SPRAAK uses Subversion (svn) for this purpose. Subversion is very similar to the popular cvs system, but without the quirks of the latter. Subversion allows for greater flexibility while reorganizing an existing code base. One can move and/or rename files in a subverion repository without breaking it. Something that's not possible in cvs.

The subversion system is primarily a set of command line tools that can be used to create, maintain and generally use repositories. It can be used in several setups varying in complexity from basic (local file access only) to medium (subversion client/server) to advanced (repository hosted via apache extension). For detailed information about subversion, we refer to the project's home-page: http://subversion.tigris.org/

The SPRAAK repository

SPRAAK uses the subversion client/server setup in combination with ssh for maximal flexibility. Currently, the repository is stored at ESAT using the spchprog account. The repository is backed-up on a daily base.

To access the repository one uses the svn client program. Only people who have been granted the rights to use the ssh-svn tunnel (see Acquiring access to the code respository) have read and/or write access on the repository.

Working with svn (the SPRAAK way)

The basic idea is that all developers have a local working copy of the code in the repository. The svn client program is used to sync and compare this local version with the version in the repository.

This document only describes the most frequently used commands. For a more extensive list of commands you can type

> svn help

For extra help about a specific command type

> svn help <command>

Initial Check-out

The following command will get the latest SPRAAK code from the repository and place it in the current directory (called workdir from here on):

> svn co svn+ssh://spchprog@spraaksvn.esat.kuleuven.be/users/spraak/spchprog/SPRAAK/repos/trunk .

If you want only a part of the repository, extend the above url with the path of the subtree you're interested in.

Once this command completed, you can go in the workdir directory and use the various svn commands explained in the following sections.

Requesting extra information

To check the status of the files in the local copy:

> svn status

To view the history for a specific file in the repository:

> svn log foo.c

To view the difference between your local copy and the latest version in the repository:

> svn diff foo.c

Checking-in Local Changes

To do an atomic check-in of all changes in the current directory (and recursive dirs):

> svn ci -m "Fixed bug 215"

The -m option allows you to give some comments on the changes. It are these comments that will finally be shown in the history of a file. Try to keep these comments short and useful.

If you only want to check-in some specific files you can add those filenames after the command.

Adding Files and Directories

You can add files and directories with:

> svn add bar.c

This will mark those files and directories for addition on the next check-in. They will not be in the repository until you do an explicit check-in. The check-in allows you to add some comments about these new files.

Renaming / Moving Files and Directories

To rename files you can use:

> svn mv foo.c bar.c

This same command can be used to move things around. Again, the actual changes will only happen after an explicit check-in.

Advanced Stuff

The svn client configuration file can be found in $HOME/.subversion/config . In that config file you can specify which file-extensions svn should ignore. It can also be used to set automatically some properties when files are added to the repository for the first time. This is especially usefull to set the svn:keywords property which is needed if you want to use automatic keyword substitution of for example the Date, Id or Author keyword.

Acquiring access to the code respository

This section is only for internal use at ESAT. At this moment we're not allowing external access to the code repository.

Create a new ssh identity for subversion usage

> cd ~/.ssh
> ssh-keygen -t dsa -f id_dsa_svn

Give twice an empty passphrase (unless you like to type passphrases alot, or use ssh-agent).

Get host spraaksvn in your known_hosts file

If you never logged on to spraaksvn, do this now.
```
> ssh spraaksvn.esat.kuleuven.be
```
Answer yes to the question if you want to continue. After you logged on succesfully you can logoff again.
```
> exit
```

Config client side

Open ~/.ssh/config in your favorite text editor.

Add the following lines to the file:

Host spraaksvn
IdentityFile ~/.ssh/id_dsa_svn
ForwardAgent no
ForwardX11 no
IdentitiesOnly yes
BatchMode yes

Save and exit your editor.

Config server side

The following steps should be done from the spchprog account. If you don't have access, ask somebody who does.
Logon with the spchprog account.
Open ~spchprog/.ssh/authorized_keys in your favorite editor.
Append the public key you generated in step Create a new ssh identity for subversion usage. This is done by appending the content of ~<your-account>/.ssh/id_dsa_svn.pub to the end of the file we're editing.

Edit this new line by prepending it with:

command="/usr/bin/svnserve -t --tunnel-user=<your-accountname>"

A complete line could look something like:

command="/usr/bin/svnserve -t --tunnel-user=johndoe" ssh-dss AAA...AGQdQ== johndoe-svn@spraaksvn

Save and exit your editor.
Logout spchprog account.

Test your setup.

Go to a directory where we can create some files.

We'll make a working copy from a test repository.

$ svn co svn+ssh://spchprog@spraaksvn.esat.kuleuven.be/users/spraak/spchprog/SPRAAK/testrepos

Let's test some commits.
```
$ cd testrepos/test/trunk
```
Modify one of the files, for example x.c
Let's see if we can detect the changes.
```
$ svn status
```
This should show that the file x.c was modified.

Let's commit the changes to the repository.

$ svn commit x.c -m "Comment for the modification"

We can check the history of x.c to see if all worked well.
```
$ svn log x.c
```
This should show a history of changes, including the author of those changes.
If you're done testing you can throw away this working copy by removing your testrepos directory.

The real thing.

Go to a directory where you want to create a working copy.
See Initial Check-out for the rest.