Practical Subversion

I've been leafing through Practical Subversion (by Garrett Rooney) over the last couple of weeks. It's published by APress, and were it not for my constant lack of time (and yesterday's mishap) I would have posted about it a while back.

At The Edge Of CVS

I'm one of those people who use CVS a lot. We're not talking about extremes like keeping my complete home directory on it, but I have a private CVS repository for some of my project stuff, a public CVS integrated with this site, and a few ad-hoc ones for a few projects. It's simple. It works. Like everyone else, I know what it can't do and have workarounds.

In a bout of synchronicity, Melo has been looking at source control systems. In fact, it seems like everyone is looking for something better than CVS: Mono switched only the other day (and documented the process), Growl has been using it pretty much from the start, and it seems to be gaining in popularity every month.

And so it is with me. I've heard the Subversion siren song too often and have been looking for a reason to dive in, or, at the very least, a decent guide.

And for that I mean something I can read piecemeal during my hectic work week and that doesn't force me to wade through a lot of the basics. Most of the stuff I've come across takes a lot for granted or spends 90% of the time comparing it to CVS (or to arch, or to BitKeeper), so Practical Subversion turned out to be a nice way to get a grip on things.

From The Top

The book starts out with the usual overview of the reasons why version control systems help the average programmer maintain his/her sanity, but does the right thing - it keeps it to two pages, and dives right in to Subversion's history and a short overview of its origin and the ways it improved upon CVS.

It is not, however, an in-depth introduction to version control - to my relief, it assumes you already know the basics and have some development experience, and dives right in.

For instance, it glosses over installation - a good thing, since you can get precompiled binaries of Subversion for just about anything these days and there is little point in wasting pages with that sort of thing - but points out the dependencies to Apache and Berkeley DB and what you should know if you have to compile it from scratch on a standard UNIX system.

It also points out which registry keys are used in Windows, but Mac users with no UNIX experience will be left wondering a bit. There are specific notes in the book regarding Mac OS X and Interface Builder .nib files, but the book is mostly platform-agnostic and duly notes where it can't be.

(Never fear, you can get precompiled binaries from Fink and a couple of other places.)

The Basics

Chapter 2 dives right in and walks you through basic operations, and keeping in line with the book's pragmatic approach, you get a working example of the basic client commands and a running comparison with other source control systems - i.e., it's not exaustive (or boring), but sticks to the relevant differences, and leaves in-depth command explanations to the Appendixes.

But the best bit (for me) was the administration overview (Ch. 3), which explained in a clear and concise way how to do things like installing hook scripts (i.e., for commit notifications) and setting up WebDAV - like installation, it's glossed over a bit, but it was clear enough for me.

Since it assumes you already have Apache and UNIX experience, it goes straight to the point and tells you what to add to httpd.conf and set up basic access control, leaving the details of Apache integration to a later chapter (Ch. 5), and hinting at the actual inner workings of the Subversion components (which also have an entire chapter to themselves alongside the Subversion C API).

Subverting Your Environment

Migrating from CVS and Perforce is also covered in the same practical way, although there isn't actually much to say in that regard - you can either use cvs2svn or just import your stuff into Subversion, so it isn't that big a deal. I did like the chapter on Best Practices, which also provided some hints on maintaining vendor branches (always a tricky thing to manage, especially when your code relies on someone else's).

If you're used to specific IDEs or web front-ends, there are also some cursory notes on common pitfalls and how to persuade Eclipse, Interface Builder, ViewCVS and others to work with Subversion. This is where I thought the book needed a lot more detail, but given its stated goal (to give you a running start without wasting your time on the basics), the number of tools covered is adequate.

A notable omission is, of course, Trac, but it is hairy enough that I understand why it might have been left out (I'm still gathering the nerve to set it up myself).


I glossed over sections like the C and Perl API overview (which are useless for me, but which look like something Melo and pfig might sink their teeth into with relish) and the Appendixes (one consisting solely of Subversion command-line references and another comparing Subversion to other source control systems), so I can't really comment on those. I did note the rather slim references to Python, but I'm biased on that regard and most of the development in that field is pretty recent.

Still, the book's practical, direct approach struck a chord with me - there is no beating round the bush to get you started using Subversion, unlike other books of the kind (you know, the ones where you spend 100 pages poring over every little meaningless detail before actually knowing how accomplish something), and the things you need (and how they work) are clearly laid out with enough context inside each section without needing to refer to the index.

Guess What, It's Readable

This last bit deserves a mention: The book's narrative style means you can actually read it, without being mired in a hodgepodge of footnotes and references (which is what most technical books these days turn out to be). Although 300 pages is a very small introduction to Subversion, you can pick up any section of the book and get to grips with the issues almost immediately, which is a major plus as far as I'm concerned.

Sure, it won't answer all of my questions. And Subversion itself is a moving target, with new enhancements coming round the bend - but I already knew that, and I only needed a quick way to get into it.

As far as I'm concerned, Practical Subversion gave me just that: A clear, no-nonsense guide to getting started, in a period where I had (as usual) very little free time to spend reading it.

All in all, it was time well spent.