Introduction

Subversion (SVN) is useful tool for collaborating on projects. It's in a class of tools called Source Control Management (SCM), of which there are many other packages available too. We will focus on SVN though, because it is open source and fairly easy to use. SVN can do things like:

track the version history of your files
revert back to an older version if you screw something up
organize a set of versions of files into a "release", that you can publish for your users
help to facilitate multiple group members simultaneously working on a project (and even on the same file!)
help to identify and resolve editing conflicts

SVN is intended mainly for source code, and not large datasets or binary documents, although you can use it to store them too if you wish. In the following tutorial, we will demonstrate how to set up a repository for your research group, and perform some basic tasks with it.

Example Repository

In this example, let's create a repository for our research group. We'll create several projects inside, and add some files to these projects. The best place to create our repository is probably in our Group Saved area, since it's safely backed up.

[araim1@maya-usr1 ~]$ svnadmin create /home/araim1/gobbert_saved/myrepos
[araim1@maya-usr1 ~]$

We now have an empty repository, so let's add a few empty projects. A Subversion directory is very similar to a filesystem directory, in that we can add files and other directories to it.

[araim1@maya-usr1 ~]$ svn mkdir file:///home/araim1/gobbert_saved/myrepos/project1

Committed revision 1.
[araim1@maya-usr1 ~]$ svn mkdir file:///home/araim1/gobbert_saved/myrepos/project2

Committed revision 2.

Notice the special "file://" URL syntax used to locate the repository on local storage. Each time we do "svn mkdir", an editor window comes up with the following text:


--This line, and those below, will be ignored--

A    file:///home/araim1/gobbert_saved/myrepos/project1

In this first line you can type something like "I added a new project". This message will be saved into the project's history, which you can view later.

If you get a message saying something like this

[araim1@maya-usr1 ~]$ svn mkdir file:///home/araim1/gobbert_saved/myrepos/project1
svn: Could not use external editor to fetch log message; consider setting the  
     environment variable or using the --message (-m) or --file (-F) options
svn: None of the environment variables SVN_EDITOR, VISUAL or EDITOR is set, and no 
     'editor-cmd' run-time configuration option was found
[araim1@maya-usr1 ~]$

you can tell Subversion which editor you'd like to use by setting an environment variable, and then you may proceed with your "svn mkdir" command.

[araim1@maya-usr1 ~]$ export EDITOR=vi

After you save your message, the project should be added to the "myrepos" repository.

Now let's suppose we want to start working on project 1. We should never edit the repository directly. Instead, we check out a working copy of the project, make our changes to the working copy, and check in our changes when we finish.

[araim1@maya-usr1 ~]$ svn co file:///home/araim1/gobbert_saved/myrepos/project1
Checked out revision 2.

Now we'll add a text file with some important information

[araim1@maya-usr1 project1]$ cd project1
[araim1@maya-usr1 project1]$ echo "here are some contents" >> testfile.txt
[araim1@maya-usr1 project1]$ svn add testfile.txt
A         testfile.txt
[araim1@maya-usr1 project1]$ svn commit testfile.txt
Adding         testfile.txt
Transmitting file data .
Committed revision 3.
[araim1@maya-usr1 project1]$

Notice how we needed to add the file to the project, after we created it. The "add" doesn't take effect until we finally commit the file at the end. Now let's check the history of project 1 and testfile.txt.

[araim1@maya-usr1 project1]$ svn log file:///home/araim1/gobbert_saved/myrepos/project1
------------------------------------------------------------------------
r3 | araim1 | 2009-12-05 03:28:26 -0500 (Sat, 05 Dec 2009) | 2 lines

Added an important file

------------------------------------------------------------------------
r1 | araim1 | 2009-12-05 03:19:39 -0500 (Sat, 05 Dec 2009) | 2 lines

Added project1

------------------------------------------------------------------------
[araim1@maya-usr1 project1]$

[araim1@maya-usr1 project1]$ svn log file:///home/araim1/gobbert_saved/myrepos/project1/testfile.txt
------------------------------------------------------------------------
r3 | araim1 | 2009-12-05 03:28:26 -0500 (Sat, 05 Dec 2009) | 2 lines

Added an important file

------------------------------------------------------------------------
[araim1@maya-usr1 project1]$

Remote access to repository

Another benefit of source control is that we can work on a remote machine, and easily keep all the working copies synced, whether local or remote. Suppose we are working on GL, and we want to work on project 1 from myrepos on maya.

araim1@linux1.gl.umbc.edu[8]$ svn co svn+ssh://maya.rs.umbc.edu/home/araim1/gobbert_saved/myrepos/project1
A    project1/testfile.txt
Checked out revision 3.

We'll append some text to testfile.txt

araim1@linux1.gl.umbc.edu[15]$ cd project1/
araim1@linux1.gl.umbc.edu[16]$ echo "more contents" >> testfile.txt
araim1@linux1.gl.umbc.edu[17]$ svn commit testfile.txt
Sending        testfile.txt
Transmitting file data .
Committed revision 4.
araim1@linux1.gl.umbc.edu[17]$

Then we'll add a new subdirectory with another text file

araim1@linux1.gl.umbc.edu[18]$ mkdir results
araim1@linux1.gl.umbc.edu[19]$ echo "some contents" >> results/output.txt
araim1@linux1.gl.umbc.edu[20]$ svn add results
A         results
araim1@linux1.gl.umbc.edu[21]$ svn commit results
Adding         results
Committed revision 5.
araim1@linux1.gl.umbc.edu[21]$

We can go back to our working directory on maya, and update it with those changes - automatically

[araim1@maya-usr1 project1]$ svn update
A    results
U    testfile.txt
Updated to revision 5.
[araim1@maya-usr1 project1]$ ls -R
.:
results  testfile.txt

./results:
output.txt
[araim1@maya-usr1 project1]$

If we had any uncommitted changes in our working copy, SVN would help us handle any conflicts. We would be forced to compare our version to the one from the repository, to ensure that our work is up to date.

There are also more advanced usages as well. It's possible to create a "tag" for a project when you reach a certain milestone - e.g. version_1.0.0. This makes it easy to keep track of which versions of individual files made it into version 1.0.0 of our program. Even more advanced usages of source control are branching and merging, which we won't go into here. These concepts take some getting used to, but can be very powerful for collaborating with your group members.

For more information, try running "svn help" at the command line. Also see the Subversion project page.

Note for Windows users: there is a nice graphical front-end for SVN called Tortoise. It's open source, so you can download it for free.