Getting started with Subversion

What is Subversion useful for?

For any project where you want to be able to keep a record of what you did, and possibly go back to earlier versions.  We strongly recommend it for theses, drafts of papers, and for code development.  Some of us keep all our lecture notes under version control.

It is particular useful for projects with more than one author, as it enables several people to work on the sources simultaneously, and (unless they make contradictory changes) to merge together all the contributions.

It is also very useful if you work on a project on more than one computer, e.g. at home and in the department, or under Windows and under Linux.  You can easily ensure that copies on the various machines remain in sync.

How do I get a repository?

See the SVN server page for details.

I get an error about the SVN repository moving, please relocate. What should I do?

If after checking out your SVN data you see an error:

svn: Repository moved permanently to 'https://svn.stats.ox.ac.uk//repo_name'; please relocate

Use the command

svn switch --relocate https://www.stats.ox.ac.uk/svn/repo_name https://svn.stats.ox.ac.uk/repo_name

to fix it.

What is it not good for?

Binary files (such as PNG or JPEG images, but not PostScript ones) that will be changed frequently.  Subversion is quite happy storing binary files, but not in merging simultaneous changes to them. It is also not good for .doc, .xls or Open Office documents as these are binary files.

Does it work on Windows, Mac OS and Linux? 

Yes, you can happily use a wide variety of OSes, and work on a project from more than one of them.  The only thing to watch is line endings on text files.  Linux and (normally) Mac OS X use LF for line endings, and Windows normally uses CRLF.  It is probably most convenient to use LF in the repository and tell the svn client to make the conversions on Windows, but many Windows programs (including most compilers and  MiKTeX) are happy with LF line endings.

See http://www.apache.org/dev/version-control.html and
http://www.zope.org/DevHome/Subversion/SubversionConfigurationForLineEndings for some helpful hints about handling line endings.

How do I know what is in my repository? 

The simplest way is to browse it using your web browser.  Point it at
 
https://svn.stats.ox.ac.uk/repos_name
 
where repos_name is the name of your repository. Accept the certificate, log in with your SVN username and password, and click on the linked file and directory names to explore. 

How do I get started?

There are two ways.  The first is simpler.
 
1. Checkout the empty repository that has been created for you.  In a  suitable parent directory
 
svn checkout https://svn.stats.ox.ac.uk/repos_name  dir_name
 
This will create a working copy of the repository under dir_name. Now  cd dir_name and create (or copy in) the files you want to add   to the repository.  Once you have a first stab at what you want
 
svn add names_of_files_or_directories
svn commit -m"some message for the logs"
 
You can add files to the repository in the same way, and if you change files, just use the second line.  To see what files (if any) need adding or committing, use 

svn status
 
To see the differences from the current repository version, use
 
svn diff
 
2. Create in a temporary directory the tree of files you want to add to the repository.  Then use
 
svn import dir_name https://svn.stats.ox.ac.uk/repos_name 

Then move a different working directory and check out via  

svn checkout https://svn.stats.ox.ac.uk/repos_name/dir_name

Once you are happy that the repository has the right files, you can  delete the temporary directory tree you imported.

How do I add a new project to my repository?

Follow the first recipe under 'how do I get started'.

I'd like to know what I am committing

If you use just svn commit you will be asked for the message in an editor, and the skeleton file will list the files with changes to be committed.

What editor? 

This is taken from environment variables such as SVN_EDITOR, EDITOR and VISUAL.  Windows' users will probably find that no editor is set, so need to set SVN_EDITOR to e.g. notepad.exe.

What are the option for these commands?

For any command typing

svn command --help

will give you a summary of the options.  If that is not enough, look up the Subversion book.

How do I found out what changes were made?

The main tool is svn log. Used on a file in the checkout directory, it list all the changes by date and with the message used when the change was committed.  If you want more information use
 
svn praise
svn blame
 
(which are glass half-full and half-empty names for the same command).  This gives an annotated listing of the file with the last revision number (and who made it) listed for every line. Cross-reference with the svn log to see the message attached to that change. 

How do I ensure that my various working copies remain in sync?

This justs needs methodical use of

svn update

when you start work on a working copy

svn commit

when you stop

Don't hesitate to commit changes often: subversion is very efficient at storing lots of changes, and large projects do have lots (subversion itself has 25,000, and R has over 43,000). 

How do I go back in time?

Subversion records every change in the repository by incrementing the revision number.  So if you know what the revision number is, use
 
svn update -r123456
 
to change all the files in the current directory to that version.  You can also do this by date.  Note that this only affects the current checkout, and you can go back to the current version by svn update.
 
If you are using a subversion client version 1.4.0 or later and you want to undo a change, use svn merge.  For example, to undo revision 12345, use
 
svn merge -c -12345 https://svn.stats.ox.ac.uk/repos_name/dir_name
svn commit -m"revert r12345"

In the department on Linux systems the client version is  1.6.17 and so the command needed is

svn merge -r12345:12344 https://svn.stats.ox.ac.uk/repos_name/dir_name
svn commit -m"revert r12345"

How do I lay out the repository?

It seems that there are two basic sorts of usage.  If you are going to want to 'branch' your work you need a more complicated layout, option B here.
 
A) For simple use, we suggest you keep each project in a separate directory directly under repository top directory.  You can checkout the project separately by
 
svn checkout https://svn.stats.ox.ac.uk/repos_name/dir_name
 
and work it anywhere in your file space.
 
B) Software projects often need to branch.  You work on version 1 of your software, release it, and then start work on version 2. Meanwhile you (or someone else) find an error in version 1, and you want to release version 1.1.  This is easiest if you create a branch at release time, and to do that you need to create the repository to allow branches.  The way to do that is to create a directory tree like
 
dir_name/
   trunk/
   tags/
   branches/

 
Then create the files for your project under /trunk and commit them.  We suggest you check out just the trunk by
 
svn checkout https://svn.stats.ox.ac.uk/repos_name/dir_name/trunk dir_name
 
The extra complexity comes into use when you want to create a branch. See http://developer.r-project.org/SVNtips.html for how the R project handles branches.  

Do I need to worry about text vs binary files?

Usually no: Subversion will figure this out for itself and mark the file appropriately. 

    How do I include Subversion version control information in a LaTeX file?

    In this example, the last changed date, current version number and name of the author will be added to a LaTeX file called exercises.tex.

    1. Add

    \usepackage{svn-multi}

    to the preamble. There are other packages which allow LaTeX to access svn data, but svn-multi appears to be the most flexible.

    2. Add

    \svnidlong
    {$LastChangedBy$}
    {$LastChangedRevision$}
    {$LastChangedDate$}
    {$HeadURL$}

    to the preamble.  These commands (actually macros) give you access to the subversion change control information. You may choose not to use all the information in the document but it useful to include all the options. You could add

    \svnRegisterAuthor{hutchins}{Susan Hutchinson}

    which associates your full name with the username that owns the repository.

    3. In the directory where your .tex file is stored enter

    svn propset svn:keywords 'LastChangedBy LastChangedRevision LastChangedDate HeadURL'\ exercises.tex
    property 'svn:keywords' set on 'exercises.tex'

    4. Add

    \small{Last changed on \svnday  -\svnmonth -\svnyear \space at \svnhour :\svnminute \space by \svnFullAuthor{\svnauthor} \hfill Revision 1.\svnrev}

    to the place in the .tex file where you want the version control information to appear and save the changes. In this case the typeset version will read

    Last changed on 23-07-2007 at 12:03 by Susan Hutchinson                           Revision 1.30

    5. Make sure that the .tex file compiles and then close the file.

    6. Enter

    svn status

    You should see

    MM     exercises.tex

    which means that exercises.tex has changes both to the content and properties which need to be commited.

    7. Enter

    svn commit -m"Added subversion information."

    to save the changes on the repository.

    8. Compile the .tex file twice and the version control information should appear.

    For more information about the svn-multi package see

    - The package documentation: http://www.ctan.org/tex-archive/macros/latex/contrib/svn-multi/
    - A very useful article from the PracTeX journal: http://www.tug.org/pracjourn/2007-3/scharrer/