| February 13, 2009 12:11 am

Anyone who has worked on a major project knows the panic of losing their work.  It happens for reasons that are too numerous to count; even to the most organized, disciplined and obsessive.  A hard drive goes bad, the work doesn’t get saved or it might accidentally be overwritten in a careless moment.

While some of these setbacks are inevitable frustrations of the Wordsmith (in any of his incarnations), they don’t have to be.  In this, the first of two articles, we will look at one solution that can greatly simplify a writer’s life: Subversion.

What is Subversion?

Subversion is a version control system (VCS).  If you find yourself saying, “Version what?”  You might not be alone.  Despite the fact that a good version control system can make life much simpler, it seems like very few people outside of tech circles have ever heard of them.  This is largely because version control systems have their roots in software development and content management.  Regardless of their roots, though, they greatly simplify the process of backup, archiving, and collaboration. This means that you spend more time working and less time worrying.

At its heart, software development is about writing.  Granted, it’s writing in a language that few can read and even fewer might want to; despite that, a coder is engaged in creation, editing, and keeping track of changes.  Coders may work in large teams and it is also likely that they may be working on the same files at the same, which makes the possibility of mistakes quite likely.  This can be disastrous for a computer.

You see, even stupid humans are at least somewhat intelligent.  The human mind is able to interpret where letters are and what a word should be.  If the mind expects a word to be present (which isn’t) it will simply add it.  The letters can even be all jumbled up and out of order, yet the mind can still manage to make sense of it (see the figure for an impressive example).

Olny srmat poelpe can raed tihs!cdnuolt blveiee taht I cluod aulaclty uesdnatnrd waht I was rdanieg. The phaonmneal pweor of the hmuan mnid, aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it deosn’t mttaer in waht oredr the ltteers in a wrod are the olny iprmoatnt tihng is taht the frist and lsat ltteer be in the rghit pclae. The rset can be a taotl mses and you can sitll raed it wouthit a porbelm.Tihs is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the wrod as a wlohe. Amzanig huh? yaeh and I awlyas tghuhot slpeling was ipmorantt!
Even rather stupid people are at least somewhat intelligent.  The human mind is able to correctly interpret what a word should be, even when the characters are a mess.

In contrast, though computers may be able to do things quickly – giving  the appearance of intelligence – they are incredibly and notoriously stupid.  If you ever have an opportunity to drop by a computer laboratory where budding programmers are hard at work on assignments, do so.  It will provide you with an important sense of empathy for a class of people different than yourself.

This visit will also give you greater understanding as to why programmers are so frequently frustrated.  A single space, semi-colon or letter out of place is sufficient to send a computer into hysterics. One little typo can bring a programmer’s productivity to an end. And consider this: if one errant key entry is sufficient to cause these problems, imagine the potential for error when you are working with just not a single person, but many.

Version control systems (like Subversion) simplify the work of making sure that multiple people can all work on the same files at one time.  The software automatically keeps a log of every change and who made it.  In case there is an error which cannot be repaired, you can revert to an earlier version of the file.  It’s even possible to compare a new version with an older one to see what has changed.

If you work with any kind of text (as an aspiring author, editor, coder, student, or researcher) those features should have you salivating.  Before using subversion regularly, one of my primary jobs in the research lab was to collect the edits that various collaborators had made to a research manuscript and merge them manually.  This was tremendously painful and slow.  I can testify from experience that if everyone uses Subversion, it makes life much easier.

How does it work?

A Subversion computer communicates with a central file store called a repository.  The store is where all files and the changes made to them are saved.  To work on a given project, the files are “checked out” which creates a local copy.  After the files have been checked out, they can be edited or modified.  After all of the changes have been implemented, they are then “checked back in” (or synced) to the central store.

Since Subversion is tracking the changes, only new parts are sent back to the archive.  But because the archive saves every modification, you can revert to an older copy of the file, use it for comparison or just rest easy knowing that all of your old drafts are available.

Here are a few additional hints that make working with Subversion easier:

  • While it is possible to keep your store on the local machine, this isn’t necessarily the best or most efficient way to work.  In Part 3 of the “Backup, Share and Sync” series of posts, I described how to setup a simple Subversion server using a simple home file server.  This is one really easy way to make your central store available to all the computers in your home.  There are also companies where you can find free or cheap Subversion hosting.  For collaborative projects with others, I’ve used Beanstalk with good results (Beanstalk has a free account available).
  • While Subversion works great with Microsoft Office files, simple text files, layouts/proofs (Adobe Indesign, Quark Express and Scribus) and PDF (basically anything that is text based), it doesn’t play nearly so nicely with binary data such as images.  Rather than track changes incrementally to the binary files, it creates a brand new copy of the file each time it is changed.  As a result, Subversion is probably not the best way to backup and archive images.

Okay, so I know that I’ve written an extremely long introduction, however, it is very important to know a few things about Subversion before starting to use it.  Onto more practical matters.  In the next few sections, we will look at how to get the program installed and running; after, we will look at some of the most common commands.


Though Subversion is a command line utility (and as such can be extremely intimidating), do not despair.  There are a number of user interfaces that not only make using Subversion easy, but greatly simplify using it’s most powerful features.  Probably the best GUI for Windows is a program called Tortoise SVN.  An excellent front-end for Mac OS X is called RapidSVN.  (As most people likely use a Windows machine, the screenshots and instructions for the rest of this tutorial will be from Tortoise SVN.)

The installation packages for Tortoise SVN and RapidSVN have all the files that you will need.  If running windows, be sure to download the correct version (either 32 or 64 bit) of Tortoise SVN or RapidSVN.  While the 32 bit version will run on a 64 bit machine, it doesn’t run well.  The download installation files for ToroiseSVN can be found here, while those for RapidSVN can be found here.

Getting Started

When you first start out with Subversion, there are several important terms which you need to be familiar with.  These are:

  • Project.  A folder or a group of folders that contain related files.  As Subversion is most commonly used for source code, a project is typically all of the files in a program.  For a writer, it might be the files of a book or research article.
  • Check-Out.  Copying a series of folders or files from the central repository to the local machine.  After being checked out, Subversion will track all changes made to the files and sync those changes back to the repository.
  • Commit.  Checking-in modified files back to the central store.  Only the changes are transmitted.
  • Import.  The process of adding a project to the repository for the first time.
  • Export.  Creates a copy of the files in the repository which isn’t under version control, meaning that changes won’t be tracked.

With the terminology out of the way, let’s get started!

Creating a Central Repository.  The very first thing that you will need to do is create a central repository (if you haven’t already done so).  If you are working with Subversion on your own file server, you will need to do this from the Linux command line.  Instructions can be found in Part 3 of Backup, Sync, Restore.  If you are going to create a repository on your local machine, however, setting up a repository is very easy.

On Windows, go to the directory where you will want the repository to be located.  Then, right click and select “Create repository here” from the context menu.  You will be prompted to give the repository a name.


This is probably a good time to mention that Subversion doesn’t store files on the disk in the same way the operating system does.  As a result, you can’t directly browse the repository with the explorer in Windows or the finder in Mac OS X.  Rather, you will need to look at your files by using the Repo-browser.

When it loads, the repo-browser will prompt you for a URL.  If you are accessing the repository on a server, it will look something like: http://xxx.xxx.x.x/svn/ProjectName.  If you are working on your local machine, just type the path to the file.


Adding a Folder to Version Control (Import).  To add a folder (or project) to the repository, right click on the folder then select “Import.”


You will be prompted to provide the URL of the repository where you would like to store the files.  Type in the address, in my case it is at and then click “Ok.”  It might also be good to type a description about the files or documents that you have added.  This will prove helpful should you need to revert to an earlier copy.


Once you have added the files to the repository, you can delete or archive the source directory,  it isn’t under version control yet.  We will need to check-out a copy first.

Checking Out Files (Creating a Local Copy).  To check-out a folder from the repository, right click and select “SVN Checkout …”


At the checkout screen, specify the URL of the repository you would like to check out the files from and where you would like the local copy to be created.  If you want to check out all files, then “Checkout Depth” should be left to “Fully recursive.” “HEAD Revision” will retrieve the most recent version.  Click “Ok.”


A new folder will be created with the most recent version of all of files in the project.  This folder is under version control and every change that you make will be tracked.

Committing Changes.  Once you have decided that you are happy with the additions, edits or other changes; they need to be “committed” back to the repository.  You can do this by right clicking on the project folder and selecting “Commit Changes” from the list.  The modified bits will be uploaded back to the server.

While tracking the changes to files that are already under version control is a dream, imagethings become slightly more complicated if you want to add a new file to the project.  Rather than just move the file to the project folder, you also need to manually add it to the Subversion list.  However, this is easy to do.  First, either drag or save the new file to the project folder.  Second, right click and select “Add File.”  The next time that you commit changes, the file will be added to the subversion repository.  It will be under version control.

Updating the Local Copy.  If you are working on the same project across multiple computers, it is possible (perhaps even likely) that some of the files will fail to be updated.  Luckily, Subversion has a simple solution.  Right click on the folder and select “Update.”  The newer versions of any changed files will be downloaded.  Even more impressive, instead of o
verwriting any local changes that have not yet been committed, it will attempt to merge the two files.

Note: While there will be some differences in the GUI, the process for adding, checking out, or committing files is the same using RapidSVN.

Using Subversion to Stay in Sync

In addition to the systematic backup, there is another substantial benefit to Subversion.  It can be used to sync files between different computers.  When working on a scientific article, I can check out a copy of my project folder on each computer that I own.  I can then work on the files offline at my leisure and commit the changes when ready.  Subversion performs the hard job of correctly matching up the changes.  It’s cross platform, stable and powerful.


By using Subversion, it’s possible to keep an automatic archive of important projects with their changes and even sync project folders to multiple computers.  While originally created for software developers, automatic backup and version tracking is something that can greatly simplify the life of a writer as well.  Even so, consider this article just a quick overview to Subversion and some of the principles of version control.  In Part 2, we will look at some of the more advanced features: reverting to previous files, comparing and merging differences, and resolving conflicts should they arise.


2 Responses to “Getting Started With Subversion – Part 1: The Basics”

Michael Grayer wrote a comment on August 20, 2009

This is great – it’s a shame I didn’t see this earlier!

I’m setting up a Subversion server for my PhD thesis and other academic work, and looking to try and document my experiences with it in a way that non-computer-science people could understand.

I have an office Windows computer, a Linux laptop and a Linux home desktop, and am getting forever confused as to which version of a particular article is the most recent. I’d seen SVN used for computer programming projects, and other version control systems used for publishing projects, so I guess I kinda just put two and two together.

I will be documenting my experiences with svn (and LyX as well – I notice you did a small feature about that too) over on my blog – starting at http://www.nontoxic.org.uk/?p=114 – and I think I will be referring to this guide pretty regularly now that I’ve stumbled across it!

Liviu wrote a comment on December 20, 2009

Dear Rob
Very neat intro to SVN. Thank you a lot!

Care to comment?