How to Setup A Document Versioning Tool With Subversion, Part 1 [Linux]

Popular services like GDrive, Dropbox, and Box allow you to access your files from multiple machines, but if you’d like to create your own storage system with version control, this tutorial will show you how to do it using the popular source control tool – Subversion.

Step 1: Setting Up Your Document Store

The first step is to set up a library of your documents. We’ll be using the tool Subversion (aka svn), which has the key advantage of supporting files other than plain (code) text. This means that LibreOffice files, graphics created in GIMP or Inkscape, and even audio and video are all fair game.

To create a library (or repository), we’ll need a Subversion client. I use KDE, and have found kdesvn to be an excellent choice. You can install it in an Ubuntu-based distribution with the following command:

sudoapt-get install kdesvn

Once this is completed and you launch kdesvn, you’ll see the screen below:

This is the main screen, where you’ll navigate your repository… as soon as you create one! Let’s do that. From the “File” menu, select “Subversion Admin > Create and open a new repository.” You’ll get a dialog box which allows you to enter where you’d like store the repository (I’m using “/home/aaron/myrepo” for this demo). Unless you want to manage your files like code, including the “trunk” (or the “master” copy of your files), branches (or new variations not yet incorporated into the “trunk”), and “tags” (which tracks major versions of software, like “v1.0”), you can deselect the “Create main folders” option, and accept the defaults for the other options.

Once you have created your repository, it’s time to get some documents in there. You can either drag-and-drop folders from your desktop here, or use the menu command “Subversion > General > Import folders into current.”

Tip: If you drop multiple folders into the “root” of your repository, you’ll have to select each of those individually. If you’d like to be able to do one global update that includes all the files you’re working on, make sure there’s a single folder at the root. For example, all my project folders and sub-folders are beneath a “Documents” folder.

Once these files are imported, their current versions are saved in the repository. In order to start tracking which files you’ve changed, you’ll need to download the most current version from the repository (yes, you’re downloading files you already have – the difference is when you download from the repository, Subversion also sends information on the version so it can track updates). From the “Subversion > Repository” menu, select “Check out current repository path” and select a location to re-download the files you just uploaded. You’ve just made a “Working Copy.”

When you revise Working Copies of documents, kdesvn will notify you to update the repository. Open your Working Copy by closing the repository (using “File > Close”, or the “Close” button on the toolbar), clicking “File > Open,” the selecting the directory where you “checked out” the repository path.

Tip: The distinction between the repository and the Working Copy is important – once you create the repository, you shouldn’t be working in it. You make updates in the Working Copies, and push updates from them back up to the repository.

Step 2: Updating Documents on the Repository Machine

After you have made changes to the “Working Copy” and return to kdesvn, the file, or the folder containing the file, should be highlighted in red, and have an up-arrow icon over it. This informs you that this file is newer than the one in the repository, and should be updated.

Tip: When you create new files, Subversion doesn’t automatically assume you want to include them in the repository. Fortunately, if you go to the root of your Working Copy and click the “Subversion > Working Copy > Check for unversioned items,” it will display a list of files not yet checked into the the repository. You can use the “Add Selected files/dirs” from the menu or, if there is an entire folder of items, “Add Selected files/dirs recursive” to add everything down the directory tree not yet in the repository.

When you’re ready to update the repository, right-click on the updated file, or any folder in the tree (they will all be marked in red and with an up-arrow, since the file beneath them is updated), and select “Commit.” Each time you update, Subversion will change the revision number, giving you a history of each major change to your file – at least, if you bothered to “commit” it.

In the next post, we’ll explore how to retrieve past versions of documents from your repository. And if you work on two (or three, or twelve) machines, you can access the repository from those too, and ensure you’ll always have the most recent files. We’ll also explore an easy way to do this from multiple machines, even when you’re not at home.