Subversion is a version control system much like CVS but better. See the Subversion homepage for more information.

The Faculty IT department offers the ability to host Subversion reposities for students and researchers. These repositories can be used by one or more users.

• The Subversion main page is a nice place to look for more information, especially their link page.
• Version Control with Subversion. Freely accessable book sbout Subversion.
• The PracTeX Journal 2007/3 contains several articles about using Subversion in connection to LaTeX projects.
• TortoiseSVN, special SVN client for Windows that plugs into Windows Explorer.
  For ANY Windows user this is highly recommended, very easy to install and very easy to use. Just right click on a fire or directory and use the Subversion sub-menu.
• On MAC OS X you can use the command line, as described below, but there are also a number of subversion applications (mentioned by MAC users): SCPlugin, ZigVersion, svnx, Aquamacs + psvn (works great on Linux Emacs 22 as well), Mercurial, Versions.
  You will have to test them for your self.

To create a repository, please go to svn.nfit.au.dk. The same page is used to manage the repositories. To log in use your normal NFIT user-ID and password. A special subversion password will be created and send to the email account corresponding to your NFIT user-ID.

The same page can be used to manage repositories or your subversion password.

When a repository is created an email will be send to your email account with information about the repository.

In the following we will look at the basic command line interface used on Linux. Usage of the main Windows client, TortoiseSVN, can be seen on their homepage (link above) or in the short article by Martin Scharrer, Version Control of LaTeX Documents with svn-multi, published in PracTeX Journal 2007/3. The following is among others based upon Version Control with Subversion

The basic principles for using SVN on Windows is the same as for all platforms, the interface is just different (point and click).

You use this to start a project. Let us assume we are dealing with a Speciale (danish for Master Thesis) and that you have already started writing something. So assume that in the current directory we we have the following contents (and nothing else).

master.tex
chap1.tex
litt.bib

We now want to create a project in out repository containing our Speciale.

svn import --username luser -m "Importing initial speciale" . http://svn.imf.au.dk/svn/luser/Speciale

This will do several things:

• We specify the user we want to associate with the project (this username will normally be saved in the client configuration so the username and corresponding password) is only needed once.
• We specify a comment, this is added to the log file. Anytime one commit changes (to files, that is) to the repository one should add a comment.
• We import all of the data in the current directory (that is what the . means).
• We import the data to a subdirectory (Speciale) of our repository. One might call this a project. This way we can have several different (and unrelated) projects in the same repository.

The server replies:

Adding         litt.bib
Adding         master.tex
Adding         chap1.tex

Committed revision 1.

This is a tricky concept that might confuse people. Working copy means a local copy of the files in the project that you can work on. It means getting a snapshot of the current files in the repository and setting up the working copy (a directory) to work with the repository (i.e. saving the URL for the repository and the username and password needed to commit changes). Students may need a working copy at their IMF account and one at home. After having checked out a working copy one update this working copy in order to get the newest changes from the repository (one does not check out another working copy, unless that was what one wanted).

First create an empty directory to hold your working copy. Always start in a new clean directory, otherwise nasty things might happen ;-).

mkdir Speciale
cd Speciale

Then we check out the latest snapshot from the repository:

svn checkout --username luser http://svn.imf.au.dk/svn/luser/Speciale .  

Again the . refers to the current directory.

Server reply:

A  litt.bib
A  master.tex
A  chap1.tex
Checked out revision 1.

You can check the status of your own files (this is if you have changed anything) using the status keyword

svn status

which gives the status of all files in the working copy (including subdirectories etc.). One may also just specify one file. In our case there are no chages to it will give no output. If we had made a change to master.tex the output would have been

M      master.tex

The status keyword is very usefull to check if there is some file that one needs to add to the repository. There are two extra switches that are very usefull here

-v

verbose mode, aka talkative. Show a status and revision number for all files and directories. One will see in which revision a particular file was last changed and by who.

-u

means show updates, this will show you which files in your working copy are out of date, that is which files will be changed when you perform a svn update.

Two commands that one will be using very often is therefore:

svn status -v
svn status -v -u

When we have changed something, we, of course, need to commit it back into the version control system (this is the whole point of this exercise). This is done useing the commit keyword, the syntax is

svn commit -m "Comment" 

One can also specify a particular file to commit (or check in). Without any arguments it will automatically commit all modified files in the working copy.

Server reply:

Sending        master.tex
Transmitting file data .
Committed revision 2.

If one is collaborating with several authors on a project or if one is working on the same project from several working copies (e.g. from home and at work), you will need to syncronise your working copy with the recent changes in the repository. This is done using the update keyword.

svn update

At revision 2.

If there were changes in the repository since the last time we updated the working copy, the reply may look like this:

U  chap1.tex
Updated to revision 3.

When you have a file that you want to add to the repository (these are marked by a ? when you perform a svn status) you use the add keyword:

svn add file1 file2 dir3

Note that this only markes the files as to be added at the next commit, you have to perform the svn commit inorder for the file to actually be added to the repository.

Do NOT remove the file by hand, then subversion will complain about its non-existence. Instead use the del keyword to mark it for deletion. Then at the next commit the file is deleted from the working copy, and in the repository, revision N+1 will no longer contain the deleted file.

svn del file1 file2

Please remember that deleting a file currently under revision (aka part of the repository), just means that from the next revision this file no longer exists in the list of files for this project. By knowing in which revision a file was deleted, that file can later be resurrected if nedded, see below.

Sometimes renaming a file or directory becomes nedded. Again do not do it by hand bu use subversions keyword rename

svn rename oldname newname

Here we have two options, we can look at the log, which may show us which files have changed or we can look at the actual changes to a particular file.

Having a look at the comments

Use

svn log
svn log -v

The later command will show which files have changed in the revision. Output may look like:

------------------------------------------------------------------------
r3 | luser | 2007-09-07 18:23:37 +0200 (Fri, 07 Sep 2007) | 1 line
Changed paths:
   M /Speciale/chap1.tex

started chapter 1
------------------------------------------------------------------------
r2 | luser | 2007-09-07 18:18:32 +0200 (Fri, 07 Sep 2007) | 1 line
Changed paths:
   M /Speciale/master.tex

A LaTeX document needs a document class
------------------------------------------------------------------------
r1 | luser | 2007-09-07 17:54:27 +0200 (Fri, 07 Sep 2007) | 1 line
Changed paths:
   A /Speciale
   A /Speciale/chap1.tex
   A /Speciale/litt.bib
   A /Speciale/master.tex

Importing initial speciale
------------------------------------------------------------------------

Spotting the difference

To spot the difference we use the diff keyword, i.e.

svn diff -r89:90 file.tex

to see the differences between revision 89 and 90 of file.tex.

Resurrecting a deleted file

This is well described in this part of the SVN book. First one needs to find the revision where the file was deleted. Use svn log -v for this. Then we simply do a special copy from the repository to the working copy. Assume we deleted important.file in revision 88, then the latest version of that file was in revision 87:

svn copy -r 87 http://svn.imf.au.dk/svn/luser/important.file ./important.file

Then at the next commit the file is re-introduced including its history. When commiting it might be a good idea to note in the comment that we just resurrrected this file.

Resurrecting a deleted portion of text

Say you deleted a lemma from chapt5.texthat you did not need, but now you do. First use svn log and svn diff -rrev-start:rev-end chap5.tex to find the revision number of the last revision of chapt5.tex still containing the lemma. Then simply

svn copy -r 153 http://svn.imf.au.dk/svn/luser/chap5.tex ./chap5-rev153.tex

Then get the lemma text from chap5-rev153.tex.

Firstly it is a good idea to read this part of the SVN book. It talks about the basic work cycle that you will be using when working with subversion.

Contained in the part above is Resolve Conflicts (Merging Others' Changes) which describes the process of fixing conflicts in basic terms.