Excursus

In my first post, I reported my discovery that a lot of tools that programmers use are, in fact, readily adaptable to the task of writing. In a previous post I discussed diff programs—programs for comparing differences between text files. In this post, I will be discussing version control.

Programmers and writers face at least one common problem. In writing a complex program, programmers need to track small changes over time. In writing a complex document, writers need to track small changes over time. Programmers, being programmers, have written software to meet this particular need, software that can meet the writer’s corresponding need.

There are a variety of version control systems currently available, but I will be talking about subversion, a popular open source replacement for CVS. Subversion tracks changes to a directory, saving the differences in a database. Wish you hadn’t deleted that paragraph and somehow didn’t save it in the ad hoc versions of the paper you created? With subversion it is just a:

svn cat

away.

This post will be covering installing subverion on Mac OS X. Subsequent posts will cover usage, and integration with the diff program of your choice.

Installation:

STEP ONE: Martin Ott of Coding Monkeys has helpfully provided a binary for OS X. (One cool feature of the OS X version is its keychain integration.) Download the Subversion.pkg.

STEP TWO: Unzip the subversion.pkg, click the pkg-installer and follow the instructions to install Subversion.

STEP THREE: OK, let’s test it out. Open the Terminal (located in /Applications/Utilities), and type:

svn help 

If successfully installed, you should see a helpful usage message. If not, then chances are that subversion is not in your path. (Don’t worry if you do not know what this means.) To add the relevant path do the following: Type:

cd

in Terminal and hit return to navigate to your home directory. Type:

ls -a 

and hit return to see the contents of your home directory (including the files beginning with a ‘.’ normally hidden from the Finder). If a file called ‘.profile’ exists open it up in your favorite text editor. If it doesn’t exist, create it. Now just add the following line:

export PATH=$PATH:/usr/local/bin

Save .profile and type

source .profile

and hit return.

svn help

should now return the help message.

STEP FOUR: First a bit of terminology. A subversion repository is where all your files are stored. Your working copy is a local copy of its contents where changes are made. If you are happy with them, you commit them to the repository. It is possible to have a local repository on your machine, but having your repository on a server allows for some interesting possibilities (such as syncing your files on multiple machines). OpenSVN is a free subversion server. It worked well for me. (Though now mine is on TextDrive which isn’t free.) A comprehensive list of subversion servers can be found on this page of the subversion website. If you are using OpenSVN, click on the link called ‘Create a New Project’ and follow the instructions.

STEP FIVE: Subversion can be managed on the command line. You should take the time to learn how to do so. However, like diff programs (and arguably text editing), there’s a point to using a GUI environment. There are several GUI front ends for subversion. None of the interfaces are ideal. (The killer GUI front end for subversion has yet to be written.) However, svnX is by far the best I have seen on OS X. And it is free. Download it here.

STEP SIX: When you open up svnX you will see two windows. In the window entitled ‘Repositories’, add the url and login name and password from your subversion server.

STEP SEVEN: OK, you are in the home stretch now. You have installed subversion, created a subversion repository on a subversion server, and have a GUI program to manage your subversion repository and working copy. Now all that you have to do is import your project directory into your subversion repository. Once more to the Terminal. (After this, most everything can be handled through svnX.) Type:

svn import -m "import message" /path/to/your/project/directory /url/of/your/repository

(making the appropriate substitutions for the import message and path and url) and hit return.

STEP EIGHT: Now we need to create the working copy. Move your project directory to the Trash. (Don’t worry, you don’t have to empty the trash just yet.) In svnX, click on the name of your repository in the repository window. This will open a new window. Select root and click on ‘svn checkout’. In the dialogue window, select where you want your working copy to live and click ‘open’. Now in the window entitled ‘Working Copies’ add the path of the working copy you just created and the login information from the subversion server.

Congratulations! You are now set up. Subsequent posts will describe usage and integrating with the diff tool of your choice. I you can’t wait check out the tutorial at O’REILLY macdevcenter.com and the subversion book.