Subverting the system.

Subversion, often abbreviated as SVN, is a “version control system”. Prompted by Nathan’s request to hear about collaborative software for mathematicians, and the comments on Ben’s post on the subject, I’m going to briefly describe how you might use Subversion to collaborate on a maths paper. Even better, I’m offering to set up a subversion repository for any mathematician who’d like to try it. Jump to the bottom if you already have your subversion-fu, and just want the goodies.

Why would you want to try it? Essentially because I can’t imagine how you’re currently surviving in the dark ages without it! Having met Subversion through a programming project (the sadly defunct omath.org), I’ve used it for each and every maths paper I’ve written since, and even persuaded 6 coauthors so far to jump through the required hoops. They’ve all been happy enough. The alternative, emailing drafts back and forth, and having to keep track of “who’s in charge” at any given point, seems miserable. Besides automating the process of merging changes made by several people, it provides several nifty capabilities — recovering any previous version, if something goes wrong or you rediscover the charm of dropped paragraph, as well as tools to show differences, or to “blame” a file, showing who last edited each line or section.

You might have heard of one of Subversion’s many cousins: CVS, essentially made obsolete by SVN, and perhaps darcs or git, both of which are “distributed” systems, not requiring a central repository. I know mathematicians using all 4; I know about SVN, so I’ll stick with that today.

How do you use Subversion? I’ll describe here the command line interface; if you use Windows, you should install TortoiseSVN which gives a nice “right-click” interface to all of this, but the description should translate readily. There are also GUI interfaces for varieties of Linux and OSX; hopefully someone will chime in on those in the comments. Installing Subversion is fairly simple for most people — on a debian-like system, you can use the incantation “sudo apt-get install subversion”. At Berkeley, I used the incantation “Dear Julie, could you please install subversion on the department machines? It would be really useful for me and my collaborators. Thanks, Scott”, to which she replied “Sure, done!” about half an hour later. Julie is awesome.

Each SVN repository has a URL, for example something like http://tqft.net/svn/d4. (That’s a real live URL, corresponding to the SVN repository Noah and Emily and I are using to write a paper about the subfactor planar algebras. It’s even public, if you want to play along.)

To get started, you “check out” the repository:

svn checkout http://tqft.net/svn/d4

That should create a local directory called “d4”, containing several subdirectories and files. (If you know you only want part of the repository, you can use a longer URL, like http://tqft.net/svn/d4/trunk/code.) Once you’ve done this initial check out, the commands you’ll mostly use are

svn up

and

svn commit -m "This is a message describing the changes I just made."

The svn up command “updates” your local copy, automatically incorporating any changes that other people have made on the repository. Makes sure that you’re actually inside a directory containing files under version control. If you’ve just checked out the “d4” repository described above, you have to type cd d4 before svn up will do anything. Noah makes this mistake all the time! :-)

Nearly always Subversion incorporates remote changes successfully, even if you’ve also been editing one of the modified files locally. (Be careful, though, to close and reopen any updated files in your text editor!) Sometimes it fails though, and this is called a conflict. If this happens, well, ask someone who’s dealt with one before, or go read some of the Subversion book! (Incidentally, this is a well-written and thorough resource, available freely online. You don’t need to read much of it for normal use, but the real Subversion guru will eventually need to master all its appendixes.)

The svn commit command sends your local changes to the repository. You should include a very brief message describing your changes, although I’m often lazy about this, and use a very very brief message: “”. The important rule for happy Subversion use is “commit early and often”. This only really matters when you’re concurrently editing files with other people, but Noah and Emily and I have found this a really nice way to use Subversion (three people typing at once makes for quickly growing papers)!

A few more things: when you create a new file, it isn’t automatically included in the repository. You have to use a command like

svn add my-new-file.tex

Further, instead of using commands mv, cp or rm to move, copy or delete a file, use svn mv, svn cp or svn rm, so Subversion knows what’s going on. The GUI clients mentioned above make this easy.

Finally, it’s give-away time. I’ve set up so many Subversion repositories by now (papers, all my private files, several programming projects, and repositories for friends) that I have it down to a fine art, and in particular just a few minutes startup time. So, if you’d like one for your own use, tell me:

1. The name for the repository.
   • It should be short, and alphanumeric, for example abc123.
   • You’ll end up with the URL http://tqft.net/svn/abc123.
2. A list of usernames and passwords for accessing the repository
   • I didn’t mention this above, but you’ll be prompted for a password the first time you try to make changes at the repository.
3. Whether it should be public or private (i.e. readable by the world, or just those with passwords).
4. If you’d like automatic emails every time anything gets committed, and if so which email address(es) to use. This is strongly recommended, even if it sounds unnecessary at first.

Disclaimers: I’m not promising support outside of this comment thread, and you’re on your own if my hosting company does a runner, or I do. In principle, I can read your private repository, but in practice I don’t care enough to do so. On the other hand, I’ll include your repository in my completely paranoid backup system.

If you’d prefer to do all this yourself, the command you want to start with it “svnadmin create abc123”. Hooking up the repository to apache or another webserver for easy access requires some practice, however. Alternatively, if you don’t mind paying $6 a month, http://dreamhost.com/ offers SVN hosting amongst their many other services. They’re cheap and cheerful, and every so often offline.