Subversion is a great command line utility waiting for decent GUI. While the GUI’s supplanting the command line represents the triumph of the Image over the Word, the GUI has its place—even in text editing. With respect to subversion, there’s cognitive utility in being able to visualize the structure of your repository or working copy. While there are GUI front ends to subversion, none are perfect. While on OS X svnX works reasonably well, a compelling solution to graphically representing subversion repositories and working copies has yet to be found. The ideal hybrid app has yet to be written. (The situation is not unlike MP3 players before the iPod.) Fortunately, competition is good, and competition is emerging on the Mac platform. Versions promises a clean look and simple approach without compromising on functionality. A collaboration between João Pavão and madebysofa.com, the beta of Versions is soon ready for a private trial. You can sign up for the private beta at versionsapp.com.

As promised, a post about subversion workflow, but first some basic concepts.

Commit

Remember being taught journalism in high school English class? A good story must provide answers to four questions: “Who?”, “What?”, “When?”, and “Where?” Or so we were taught.

When you commit a change, subversion records four pieces of information:

1. Subversion records WHO committed the change
2. Subversion records WHAT the change was (a description of the change)
3. Subversion records WHEN the change was committed
4. Subversion records WHERE the change was made (which files or directories in your working copy were changed)

With each change, subversion increments the revision number of the repository. You can then diff against a particular revision or retrieve a particular revision as you like.

The command:

svn commit --message "Description of change" foo.txt

will record your change to foo.txt in your working copy and the “Who?”, “What?”, “When?”, and “Where?” of this change to your subversion repository.

Update

Not only will you want to sync revisions in your working copy to your repository, but sync revisions in your repository to your working copy. The command:

svn update

allows you to do just that. Suppose that foo.txt has been changed since your last update, and it is the seventeenth revision of the repository, then the command will yield:

U foo.txt
Updated to revision 17

This means that your working copy has been modified to reflect the changes to foo.txt and that it now reflects revision 17 of the repository. The letter code U is one of several codes that can be issued. These include:

• U foo—file foo has been updated
• A foo—file or directory foo has been added
• D foo—file or directory has been deleted
• G foo—file foo has been updated but you have made local changes in your working copy not reflected in the repository but these changes do not intersect
• C foo—file foo in your working copy has changes that conflict with the changes to foo in the reposiroty

Cha-Cha-Cha-Changes

So far we have discussed committing changes to the repository, and updating the working copy to reflect the changes to the repository, but how do we make these changes.

There are two kinds of changes:

1. Changes to individual files
2. Changes to the structure of the directory

Changes to individual files is easy. Just make the changes in the appropriate editing program. You don’t need to issue in any subversion specific commands.

Changes to the structure of the directory, however, requires subversion’s help. Fortunately, the relevant commands are easy to understand.

The command:

svn add foo

schedules the file or directory foo to be added to the repository next time you make a commit.

The command:

svn delete foo

schedules the file or directory foo for deletion from the repository next time you commit.

The command:

svn copy foo bar

creates a copy of foo called bar and bar is scheduled for addition to the repository next time you commit

The command:

svn move foo bar

creates a copy of foo called bar and schedules bar for addition and schedules foo for deletion.

Reviewing Changes

Before committing your changes, it is a good idea to review the changes you made. Helpfully, subversion has provided some useful tools for ding this.

First up is the command:

svn status

If this command is issued at the root of your working copy it will yield a description of all the changes that you have made since last updating. The command yields a list of files and directories preceded by letter codes indicating the nature of the changes made. These include:

• M foo—foo has been modified since last updating
• A foo—foo is scheduled for addition
• D foo—foo is scheduled for deletion
• C foo—foo has conflicts with an update
• ? foo—subversion doesn’t know about foo. You may want to add it or remove it.

If svn status indicates that foo.txt has been modified, you may want to examine these changes in detail in order to write a helpful commit message. The command:

svn diff

run at the root of the working copy will print out a list of changes to modified files in diff format. As I observed in a previous post, diff format displays line differences, not word differences. This is not great for prose since paragraphs in text files are long lines so multiple differences in a paragraph will not be adequately represented. Fortunately, subversion allows you to use external diff programs. I will make a separate post about this later.

One more tool. The command:

svn revert foo

will roll back the changes you made to foo to the state foo was in when the working copy was last updated.

The Workflow

With these basic concepts in mind, we can now describe your workflow:

1. Update your working copy
2. Make changes to your working copy
3. Review your changes
4. Resolve any conflicts (to be described in a separate post)
5. Commit your changes.

Subversion was designed for multiple programmers to work on a given project. What benefits does all this provide the single user? Besides providing a database of all changes and a record of these, the workflow really comes into its own when working from multiple locations. Suppose you are working both at home and at work on different machines. Adhering to this workflow will make sure that you are always in sync. This is a vastly more efficient and non-ad hoc framework for keeping your mission critical files in sync than emailing them or keeping them on a flash drive. These methods are helpful, yes. But their ad hoc nature is ultimately a recipe for confusion.

One final thought. GUI front ends such as svnX are helpful, but you should try to master the command line basics. And always remember, the command:

svn help

is your friend.

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.