27 Jan 2010, 7:58 p.m.

Command-Line Subversion Tutorial, Part 4

This is the fourth and final part in my series of posts covering command-line Subversion. In Part 3 I promised to return and talk a little bit about using version control sensibly and appropriately, so this is me finally getting around to it.

A lot of these points aren't specific to command-line Subversion, or even Subversion in general, but are based on a good few years of working with version control, and may just make your life a little bit easier all the same.

Use Version Control

This point sounds a bit obvious, especially in a blog post about version control, but still there are individuals and teams out there actually getting paid real money to develop software, and yet not using version control. If this is you, you're probably fed up with people telling you you're doing it wrong, but I'm going to echo that, because you are.

For the rest of us that are using version control, let's learn to use it well. It's really valuable to free yourself from relying on GUI tools like Tortoise, for example.

As with any library or framework, if you really get to know the features that VC offers, you'll find that more often you'll be able to call on standard tools that are designed for specific job - such as svn:externals - rather than re-inventing the wheel, as we all see done so often. I guess this is the bit these tutorials were intended to help with.

Moreover, use version control ubiquitously. You're probably keeping your code in there, but what about documentation, configuration files and the like? For my own part, I'll tend to use Subversion to store all sorts of writings (unfinished blog posts spring to mind), university assignments, and invoices. In fact, if anything is worth keeping, it's worth keeping in version control.

Atomic Commits

Where possible, it's worth trying to make commits atomic, in the sense that all changes that relate to a feature or fix, or some other meaningful unit of work, are contained in one commit, and similarly that no unrelated changes should make it into the same commit.

This practice will make your changelogs a lot easier to follow, for a start. Furthermore, if you need to back out a feature, that can be done with a single reverse-merge on a single revision number. Likewise, merging a changeset into another branch becomes a case of merging in one revision, which is a lot easier than picking through numerous revisions working out which changes to which lines of which files you want to keep and which you want to discard.

Meaningful Commit Messages

On the subject of making logs easier to follow, it's always valuable to enter a concise, meaningful commit message when the time comes to commit your changes. In the past, I've worked with developers who tended to enter no message at all, and I find this to be deeply unprofessional.

Part of the problem is that various GUI tools allow you to get away with this. For example, Tortoise used to add a commit message consisting of a single space, if you were careless enough not to add one yourself. Later versions simply add the revision number of the commit, which is roughly as useless as a blank space.

Happily, if you're working on the command-line, you will be dropped into vi or another editor, should you fail to add the -m switch when you svn commit. Still, even vi can't force you to make that commit message meaningful, so do take a moment to think about what it is you're committing and describe it succinctly.

Not only will you thank yourself later, but as I mentioned, it's a mark of professionality. You'd expect it from your colleagues, so show the same respect to others.

Commit on Green

If your code has unit tests (and if not, why not?) do make sure to at least run those test before committing. In fact, make every effort to make sure that when you or your colleagues take a checkout or an update of the code, their working copy is going to, well, work, and the tests are going to run and pass.

The alternative is that they won't be able to continue with their work until they've fixed the mess you've made, and it isn't hard to see how that could be annoying.

It is for these reasons that Continuous Integration is becoming increasingly popular: a CI server will monitor your VC repository for commits, and when it spots one, will check out the code automatically and run the tests. In this way, the team will be informed as soon as someone "breaks the build", and problems can be rectified at source, rather than being discovered some unspecified time down the line, no doubt at the most most inconvenient moment.

Even if you do not have Continuous Integration in place yet, this is once again really just a case of professionality and respect for your colleagues, so make sure you commit only on green.

Restrained Use of Branching and Tagging

When looking to define a version control "policy" within an organisation, it can be very tempting to try to come up with a complex branching and merging strategy that can cope with any eventuality. This approach, however, is unwise, and it's usually better to employ a minimum of branching, and therefore merging.

This is because there is a very real cost in terms of time and effort (and thus money) that comes with any additional complexity you introduce up front, and this is as true in the context of version control as anywhere else; merging branches and resolving the inevitable conflicts can be a huge pain, regardless of which version control system you use.

The best rule of thumb I can offer is simply not to branch unless you have a really good reason. Really good reasons for branching do exist, but in many teams you will find only two scenarios that do justify it.

The first is the concept of a "release branch", whereby code that's about to be put into Quality Control and thence hopefully released becomes a branch of its own. That allows you to make any last minute tweaks in that branch, while development on the trunk forges ahead unhindered. Tweaks will of course need to be merged back to trunk, and even a release branch can lead to significant pain if your release is sat at that intermediate QC stage for any longer than a day or two, so tread carefully.

Perhaps the other situation that might justify a branch is when an individual developer wants to make some very experimental changes to a codebase. Perhaps these changes might be large enough to justify a few atomic commits, but the developer doesn't want them making it into the trunk for the time being.

This is called a "developer branch", and again, any real, valuable work done in the branch will have to be merged back to trunk, so if this is a possibility, it's worth being careful not to let the code in the branch diverge too far from trunk or it'll be painful to merge it. It's interesting that Git effectively forces a developer to take this approach before starting work. Subversion leaves the decision up to you.

No Locking

When you check out a working copy of part of a Subversion repository, it is possible to "lock" that part of the repository so that no other developer can commit to it. I have purposefully not covered this feature here as it's one of the most anti-social things you can do, and completely misses the point of version control, not to mention teamwork.

I can think of perhaps one case in which locking could be justified, but it's so rare that I won't tell you what it is. Suffice to say that if you are sat there thinking "do I need to lock this?", the answer is no.

It's actually trivially easy to override a lock, so it really doesn't achieve what you thought it might anyway.

Conclusions

Well, that's it from me on the subject of Subversion for the time being. It's been an interesting ride, and it's gratifying that these posts quite quickly became some of the most the most popular items on the site. Still, it'll be nice to tackle some different subjects in due course.

I'll end by pointing you, yet again, in the direction of Pragmatic Version Control with Subversion by Mike Mason, as it's easily the best book ever written on the subject of using version control, and using it well.

Previous Posts in this Series:

Chris

I read all four of articles on Subversion. There were so easy to understand and enlightening.
Thank you so much for doing such a good job!