Version control for non-programmers with Subversion

Imagine a utility that lets you make an annotated backup of any of your project files with the click of a mouse or a single command. It would let you review the history of your backups and recover any version you wished. And it would integrate with your file browser and would keep track of files that have changed since your last backup. The utility exists — Subversion, and its companion program TortoiseSVN, can help you safely manage your files as you work with them.

Subversion is one of a class of programs that has been used by programmers for decades: the source code control system, which developers use to manage changes to program source code. Such software has features that enable large teams to work in a distributed environment on the same files while keeping track of who has done what, and when. But even if you work by yourself on spreadsheets and word processing documents, you can harness the power of Subversion to eliminate the need to litter your directories with files like “forcast.xlsOLD” and “Presentation.docFirstDraft.”

To get started with Subversion you’ll need to download the latest version from the Subversion Web site. If you’re using a Linux system, you should install Subversion from the program repository for your distribution (using apt, yum, or up2date). For Microsoft Windows users, the Subversion team has made a Windows-style installer.

If you are using a Windows system, you should install TortoiseSVN as well. TortoiseSVN allows you to execute Subversion commands directly from the Windows Explorer file manager by adding a set of right-click context menus to your files and folders.

Once you’ve installed Subversion and TortoiseSVN on your system, you’ll need to set up a Subversion repository where the program can keep the copies of the documents that you’ve “checked in” to its database. Subversion saves only the differences between versions of files that you’re storing in its repository, saving space in comparison with keeping multiple copies of the files. Subversion can always recreate any revision of a file.

To create a repository, at a command prompt issue the following command:


svnadmin create --fs-type=fsfs/data/SvnRepository


The directory you specify should be an existing empty directory.

Alternatively, using TortoiseSVN, right-click on an empty directory (we’ll assume C:SvnRepository). Select the “TortoiseSVN->Create Repository Here…” menu item. You’ll be prompted to select a repository type. As with the command-line example, choose fsfs.

We’ll assume that you intend to keep all of your Subversion-controlled documents in a single directory called ProjectDocs. If you’d like to set up more directories to work with Subversion, repeat the setup steps below for each directory in question.

Before Subversion can manage your documents, you must import them into the Subversion repository. To do so, change directory to your ProjectDocs directory. Make sure the directory (and its children) contain only the files you wish to store in the Subversion repository. Issue the following command:


svn import . file:///data/SvnRepository/ProjectDocs


You’ll note that we’ve used a file:// URL to specify a location within the SvnRepository that we created earlier. When you issue this command, you’ll be placed in an editor in which you can enter a description of this directory. When you save and exit the editor buffer, all of the files (and subdirectories) in your ProjectDocs directory will be copied into your Subversion repository.

The process with TortoiseSVN is about as simple. Right-click on your ProjectDocs directory and select “TortoiseSVN->Import…”. In the resulting dialog, you can browse to the Subversion repository you created and add to the URL the directory within the repository you want to import into. In our example, the URL to import to will be file:///C:/SvnRepository/ProjectDocs. As with the command line, you’ll be given an opportunity to describe the change you’ve made.

When you import a directory into Subversion, it is not converted into what is called a working directory — that is, a directory that’s connected to the Subversion repository and allows you to commit revisions or changes to your documents to the repository. To create a working copy of your ProjectDocs directory, first rename the one you just imported to something like ProjectDocs.presvn. Then issue the following command to check out your working copy:


svn co file:///data/SvnRepository/ProjectDocs ProjectDocs


When you issue this command, Subversion will create a new “working copy” of your ProjectDocs directory. After you’ve verified that it’s complete and correct, you can delete the one that you’d moved out of the way.

To create a working copy with TortoiseSVN, right-click in the directory in which you want to create your working copy and select “Check Out…”. You’ll need to use the same URL that you used to import the directory (it should be in the drop-down list).

Now any time you make changes to one of the files in your ProjectDocs directory you can “commit” them to the Subversion repository by issuing the command svn commit while in the directory. With TortoiseSVN, right-click on the file or directory you wish to commit and select “Commit…”. When you issue the command, Subversion will scan the files in the directory and copy all of the changes you’ve made to the repository. As with the import command, you’ll be given the opportunity add a comment describing the changes you’ve made. If you want to commit only a particular file, you can pass the name of the file as an argument to the commit command.

Now that you’ve set up your ProjectDocs directory you can work with your documents as usual. Whenever you reach a point that you’d like to preserve, simply commit the file or the directory. In the future, if you create a new file in your ProjectDocs directory (say NewFile.doc) issue the command svn add NewFile.doc. After that, you can commit the file as usual. TortoiseSVN provides a “TortoiseSVN->Add” context menu for the same purpose.

Whenever you commit anything to your repository, Subversion increments a revision number. You refer to previous versions of your files by this revision number. To see the revisions of a particular file (say MyDoc.doc) execute the command:


svn log MyDoc.doc


This will show you the revisions of your file and the descriptions you entered when you committed the changes. To get an older revision (say 6) of your file, make sure you’ve committed any changes to the file. Then issue the command:


svn update -r 6 MyDoc.doc


Your current copy of the file will be replaced with the file from back at revision 6 of your repository. When you want the current version back, just issue the update command without the -r option. TortoiseSVN has “Show log…”, “Update to revision…”, and “Update…” context menu items that let you accomplish the same things.

Those are the basics of working with Subversion as a private data management utility. Obviously software that’s designed to work with hundreds of files and developers at a time has significantly more features and capabilities. If you’d like to learn more about how Subversion works, the excellent Subversion Book is the place to start.

Day-to-day use of Subversion is easy. Just commit your files whenever you’ve reached a point that’s worth saving and describe the changes that you’re committing. It’s remarkably liberating to be able to attempt significant changes to a document when you know that it’s a simple matter to recover a previous version with a single command or click of the mouse.