Accessing the FieldTrip source code through SVN

The FieldTrip code base is managed using the Subversion source code version control system, also known as SVN. Below you will find details on how to access the source code repository. The documentation below only applies to developers, regular users should use the copy on /home/common/matlab/fieldtrip (inside the DCCN) or the copy on the ftp server (outside the DCCN, see download).

A read-only version of the SVN repository is available on http://code.google.com/p/fieldtrip, which is synchronized every evening with the in-house development version. You can use it to keep up to date with the latest updates of the source code, to revert to older versions, and to track all individual changes to the files.

On Linux and Mac OSX machines the SVN command line utility is usually installed by default. The recommended SVN client for Windows is http://tortoisesvn.tigris.org. Please scroll down for detailed information on how to use SVN on Windows.

The source code is managed using SVN/Subversion and the repository is hosted on svn.fcdonders.nl. The following information is aimed at those people that have been granted write access to the SVN repository.

The server that is hosting the FieldTrip source code repository is only accessible through ssh. That means that you can only access it if you have an ssh account. The default account names and passwords for people working at the DCCN are the same as for the SSH tunnel server. External contributors can apply for an account by sending Robert an email.

To test the access, you should try the following

ssh yourname@svn.fcdonders.nl

After logging in on the svn server using ssh, you can change your password with the “passwd” command.

To prevent that you have to type your password every time you do “svn update” or “svn commit”, you can exchange your ssh keys between the mentats and the svn server. That is explained in more detail on the DCCN intranet.

To check out your new working copy of fieldtrip, you can type

svn checkout svn+ssh://yourname@svn.fcdonders.nl/home/svnroot/fieldtrip/trunk

This gives you the trunk, i.e. the main development and release branch. It being called the “trunk” is the SVN convention and not my choice. For your convenience, I strongly recommend to do

mv trunk fieldtrip

or

mv trunk fieldtrip-dev

to rename the directory to something more usefull. There is no harm in that. If you go into that directory, you'll see that it contains the complete fieldtrip code base (at leat the parts that were part of the normal release version). This is where we should continue working on.

If you have modified a function, you should send the modifications to the repository like this

svn commit existingfunction.m

The svn command will then ask you to write a log message. In the log message you should indicate what you changed. The default editor for writing the log message is vi, which is a very powerful, but also slightly user-unfriendly editor. Once in vi, you should press the “i” button, type the text you want, press escape, type ”:wq” and the log message will be recorded. See http://www.linuxjournal.com/article/6542 for a “getting started with vi” document.

If you haven't set a standard text editor yet, you may receive an error when first trying to commit code with svn. The editor is used to specify the comments that are logged. There are different ways to solve this, see http://svnbook.redbean.com/en/1.5/svn.advanced.externaleditors.html. What you can do is to add a line 'editor-cmd = vi' under the heading [helpers] in the ~/.subversion/config file. Another option would be to set an environment variable in your .bashrc script such that it will be created every time you login. Yet another option is to use

svn commit existingfunction.m -m 'my log message'

in order to specify a log message while committing.

In general it is wise to carefully check the changes prior to committing. You can check the difference between your present working version and the version in the repository like this:

svn diff existingfunction.m

So in general the safe way of committing your changes to the function is by typing

svn diff existingfunction.m

svn commit existingfunction.m

If you create a new function, you have to add it to the repository like this:

svn add    newfunction.m
svn commit newfunction.m

TortoiseSVN (http://tortoisesvn.tigris.org) is a fairly comfortable SVN client for the Windows platform. It integrates into the Windows Explorer and shell context menus and provides GUI controls for most (if not all) SVN tasks. Since the FieldTrip repository needs to be accessed via SSH, it is suggested to also install Putty and use a private/public key pair to avoid typing passwords repeatedly.

Using public/private key authentication is completely optional, but really convenient in the long term. With one exception, you will need to do the following steps only once.

If you don't already have it, get the PuTTY software package from http://www.putty.org/. After installation, start the application PuTTYgen to create an SSH key: Select SSH-2 RSA and 1024 bits, then press the Generate button and wiggle the mouse for a few seconds until your key is generated. You should now see a public key, a fingerprint, a key comment, and two input fields for a Key passphrase. This is something like a password that protects your key, and it is strongly recommended to use one, because effectively the passphrase will play a similar role to the password on the SSH server. Save your private key to some location that only you can access, and add your public key (the contents of the top-most textbox) to the authorized_keys file on the SVN server.

If you didn't understand the last part, these are the steps: With your PuTTYgen still open, start PuTTY and type svn.fcdonders.nl into the Host name field. Click Openand login with your username and password. Type

ls -la

and make sure that you have a directory called .ssh. If this does not exist, type

mkdir .ssh

You should also make sure that this directory can only be accessed by you, so if you just created it, please also type

chmod 700 .ssh

Next, change into the directory and edit the authorized_keys file using

cd .ssh
vi authorized_keys

Now comes a tricky part: You need to paste the public key from the PuTTYgen window into this file. First, mark the contents of that text field and press CTRL-C, then change back to the PuTTY window and press i for insert. Right-click on your mouse and the key should appear. Press Return, Esc, and then type :wq and again press Return. The text editor will now save the file and exit. You can check if things went right using

cat authorized_keys

which should print out your public key. Finally, please make sure that only you can read this file and close the SSH session:

chmod 600 authorized_keys
exit

That should be it.

Once you have the public key in place, you will need to start Pageant (from the PuTTY collection) on your local computer. You will get a new symbol (computer with a hat) in your system tray. Double-click this icon, select “Add Key”, point to your private key file, and finally enter the passphrase to activate the SSH key. From now on, you should be able to login without typing the password, which you might want to try using PuTTY itself.

Your passphrase and key are only stored until you log off from your Windows box, so you will need to start Pageant and re-enter your passphrase everytime you come back.

You should create an empty directory (here we use D:\src\fieldtrip) and open this directory in an Explorer window. With TortoiseSVN installed, you should get a context menu like the following:

After selecting “SVN Checkout”, enter the following into the dialog window, but replace LOGIN by the username given to you:

Click OK to start downloading the files. If you don't use Pageant, you will need your SSH password.

TortoiseSVN comes with in-depth documentation which you can browse here: http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug.html For convenience, we'll just cover the three most important use cases.

In order to merge changes from other people into your local copy, navigate to the directory you want to update, right-click and choose “SVN Update”.

In case you and other people have worked on the same parts of the same files, these “conflicts” will show up in the message window of TortoiseSVN, and also the icon of those files will look different.

To compare your local version to what is currently in the central repository, right-click a file and select TortoiseSVN - Diff. A new window will display both versions of that file side-by-side and also highlight the differences.

Once you are sure about your modifications and want to merge your work back into the repository, right-click a file or a folder and select “SVN Commit”. If you get an error message, you probably first need to update your local copy and possibly resolve conflicts.

If you need more information on svn, this can be found in the faq http://subversion.tigris.org/faq.html and in the online documentation http://svnbook.red-bean.com/.