Another post in my series on subversion, a free, open source version control system:

• Subversion
• Subversion, Serendipity, and Discipline
• Subversion and the Single User
• LaTeX and Subversion
• Circle Six Subversion
• Subverting Difference

Today we’ll look at three ways that subversion interacts with my favorite text editor, TextMate:

1. TextMate’s subversion repository
2. TextMate’s subversion integration
3. Keeping local modifications to TextMate in sync across multiple computers with subversion

TextMate’s Subversion Repository

In Prefences → Software Update you can set TextMate to automatically check for updates (recommended). You can also set it to watch for cutting edge updates. Cutting edge updates add advanced functionality and some bundles require this setting. In a way, the label is misleading, since the cutting edge updates tend to be very stable. If, however, you want the bleeding edge of TextMate development, you will have to access TextMate’s subversion repository, http://macromates.com/svn/Bundles/trunk/. There you will find bundles, plugins, support files, themes, tools, and more. Instructions about how to checkout bundles from the subversion repository can be found in the manual (RTFM, baby), and the wiki. These should definitely be read. But above all check out Haris Skiadas’ excellent tutorial.

TextMate’s Subversion Integration

TextMate, like other advanced editors on OS X such as BBEdit and Aquamacs, enjoys subversion integration. So instead of working with subversion from the command line or with a subversion front end like svnX, it is possible to work with subversion directly from your text editor. ⌃ ⇧ A brings up a menu with common subversion commands. If you have opened your working copy as a TextMate project, then selecting the root of that directory and selecting `status’ will bring up an HTML window with the output of the command:

svn status

Click on the thumbnail below for a picture.

As you can see, the HTML window not only shows the relevant files and their status, but it allows you to perform certain actions—you can add, revert, diff, and commit. The diff command displays line differences—not great for prose, as I have emphasized here and here. Fortunately, selecting commit brings up the following dialogue window:

Notice that you can diff from here as well. However, this will use whatever diff program you have assigned as the value of the shell variable

TM_SVN_DIFF_CMD 

in Preferences → Advanced → Shell Variables. Setting the value of this variable to fmdiff will allow you to display word differences graphically in FileMerge.

Keeping TextMate in Sync

One of the great things about TextMate is how easily configurable it is. Even if you are not a programmer, after a while you will find yourself writing snippets, commands, and maybe even entire bundles. Suppose, however, you work on more than one machine—say, at home and at work. It would be great if you could keep these local modifications in sync. (Frustration is an essential tab trigger that works on one but not another copy of TextMate.) Fortunately there is an easy solution. Just commit:

~/Libray/Application Support/TextMate

and

svn up

will keep you up to date on whatever machine you are on.

Subversion allows you to compare the differences between revisions of a given document with the command:

svn diff

Let’s begin with the simplest and most common use of this command. But first a bit of terminology. Each time a change is committed to the repository its revision number increments. Revision keywords can be used instead of revision numbers. BASE is a revision keyword and refers to the pristine copy of an item in a working copy. The pristine copy of a file is a copy of your file as it was the last time your working copy was updated. It resides in the .svn directory within your file’s directory. So if your file is foo and it resides in directory bar, then running:

ls -a

in directory bar will reveal:

.svn
foo

.svn is an administrative directory that subversion makes use of and you should never modify it. Other useful revision keywords are:

• HEAD—the latest revision in the repository
• COMMITTED—the last revision in which the file changed before BASE
• PREV—the revision that precedes the last revision in which the file changed before BASE, that is, COMMITTED - 1.

The command:

svn diff foo

will compare the foo with BASE, that is, its pristine copy. So it will reveal the changes you have made to foo since you last updated your working copy. This is one of the more common uses of svn diff since it provides information necessary to write an informative commit message.

That’s pretty useful. But sometimes you may want to do something more. Fortunately, svn diff comes with a slew of options that allow for a fair amount of flexibility.

First, suppose you want to compare the modifications that you made to your file with an older revision, say, revision 17. The command:

svn diff -r 17 foo

allows you to do just that. It compares foo as it was in revision 17 with foo as it presently is in your working copy.

Second, suppose you want to compare the differences between to older revisions, say revisions 17 and 23. The command:

svn diff -r 17:23 http://url/of/your/repository/foo

will display these differences.

One really useful option is –diff-cmd. This option allows you to pass arguments to an external diff program. Why is this useful? Well svn diff only displays line differences. If you are writing prose in a text editor, paragraphs are long lines. What would be more useful is for word differences to be displayed. The option –diff-cmd allows you to use an external diff program that displays word differences.

I like to use Apple’s FileMerge, a graphical diff program that can be opened from the command line with:

opendiff

Unfortunately, opendiff and svn diff use different arguments. So to get opendiff to work with subversion requires a shell script wrapper. Fortunately, Bruno De Fraine has done the heavy lifting. His script fmdiff is just such a wrapper. fmdiff can be downloaded (or checked out) form this link. If you install fmdiff in /usr/local/bin or ~/bin as is your preference and make it executable, you could then run the command:

svn diff diff-cmd fmdiff foo

to reveal the differences between foo and its pristine copy in FileMerge.

Bear in mind, if you want to use an external diff program, say, GNU wdiff, you may very well need to write a wrapper script to accommodate a difference in arguments.