Cornerstone 2 – Annotations

cornerstone-icon (1)


I hope that you’re enjoying this series of reviews on Cornerstone 2. It’s turned out to be quite a lot more than what I’d anticipated it originally being, especially the in-built diff support review. So given that, I’m going to slow down a bit, just a bit with this third part in the review and focus on Annotations. Covering annotations nicely overlaps with both the previous article on in-built diff support and for the upcoming log viewer.

Over the next 1 – 2 weeks, we’re covering the remaining three features so stick around for the series and see why it’s the tool to use. Also, keep reading on, for a chance to get 10% off the retail price. Who said there’s not a free lunch (or a discount code anyway).

What are Annotations

Annotations make available SVN’s blame functionality. If you’re not familiar with blame, it’s the feature of SVN that allows you, or other members of your team to inspect the changes to one or more files in your repository and see who changed what, when and, if they’ve provided useful commit messages, why.

Just like some of the other features of SVN, including diff and merge you can constrain the annotation to be limited to one or more revisions based on a difference from HEAD, PREV, COMMITTED, BASE or an arbitrary date or revision number.

To get a more complete appreciation of what’s available have a look at either the svn terminal help information with ‘svn help blame‘, or click ‘Help → Subversion Documentation‘ in Cornerstone.

NB: I was quite, pleasantly, surprised to find that the latest, 1.6 at the time or writing, subversion documentation was included with Cornerstone. That’s a little time saver that I hadn’t expected. Saves you downloading a copy on your own.

Side Note: It may seem trivial to have such a feature, depending on your background. But it really is a vital requirement in a mature version control management system. All too often developers either talk about good documentation and don’t do it, or just plain don’t get why they should.

So if you’re involved in a team that has this problem, or you’re a bit lax yourself, I hope that you will see through the course of this article why the combination of annotations and proper commit messages make for a winning project.

Know what who’s done what

annotations in cornerstone 2

annotations in cornerstone 2

Getting back to annotations. The implementation of annotations in Cornerstone comes in two parts. First, there’s the augmentation to the in-built diff support, the second is the floating legend window. As you’ll remember from the last post, the in-built diff support allows for comparing any number of files in your working copy to see what’s changed and that at the bottom of the diff window, there were a number of options that you can enable and disable at will.

Enable annotations in Cornerstone 2

Enable annotations in Cornerstone 2

Viewing Annotation Information

the cornerstone 2 annotation popup

the cornerstone 2 annotation popup

One that we didn’t cover then, was enabling of annotations. Enabling annotations subtley augments the diffs in the diff gutter. Clicking on the gutter displays a popup window which displays the following information about the commit:

  • Revision number
  • Author
  • Date/Time
  • Time from now
  • The commit message

If you click the gutter once, a minimalist popup appears with everything but the commit message. If you double-click the gutter, the commit message is displayed. I’m assuming that this is to focus on a least amount of information required approach. If you want more, you can get it, but you’re not overwhelmed should you not need it.

annotation information displayed in Cornerstone 2

annotation information displayed in Cornerstone 2

So the information’s displayed quickly, clearly and concisely. One good point about this is that I’ve never known it to obscure the gutter of another commit. So you can inspect one change after another as suits your need without having to first close the popup, or scroll or change the window size to be able to view details on another commit.

Another nicety is that the change is given a soft shadow, so you’re always knowing exactly what’s in focus.

The Legend Window

the cornerstone 2 legend window

the cornerstone 2 legend window

The legend window is a real gem. Always floating, translucently, above the main Cornerstone window, the legend window provides more comprehensive details, in an overview or managerial manner, about the changes in the current file.

With it you see the following:

  • The amount of authors who changed the file
  • A timeline of the changes by each author
  • When the file was first changed and most recently changed
  • and at what revisions

I think it’s an interesting approach that Zennaware have taken with the legend window. Depending on the screen resolution, it can get a little bit in the way, but with a suitably large enough resolution this isn’t much of an issue.

The window does grow the more developers worked on a file, but through the use of subtle, petite, scrollbars, the effect of this is largely mitigated. You can see an example of this in the image below, which is taken from the online documentation. I don’t want you to feel that I’m regurgitating the online help; I’m not. It’s just that the sample project I’ve been using only has me as an author.


The project legend window

A subtle, yet helpful feature is an icon on the committers line. The last committer has a filled in circle, the oldest committer has a hollow circle and the amount that the circle is filled in degrades from most recent to least. To be honest, it’s not something that I’d taken much notice of until I was reviewing the online help.

So for that reason, I’m not going to plug it overly. I realise that up to this point, I’ve been very positive about the whole application; but this was a little feature I’d overlooked. Now that I’m aware of it, I see it as another example of what Chris Shiflett refers to as ambient signifiers. Those little things that are carefully used throughout Cornerstone that help you do what you need to, without shouting at your for your attention, nor getting in your way.


Ok, so here’s where we get to the end. Is the annotation feature in Cornerstone 2 worthwhile or not. Wholeheartedly, yes it is. From the ability to fit so much in to an existing window in such a clean and coherent manner, to making the whole lot as unobtrusive as possible, along with my personal preference for having a good eye for colour balance. Annotations are a feature that I’m sure you will benefit from time and time again.

Don’t forget you’re discount

I hope you’ve enjoyed this review of annotations in Cornerstone 2. I’m so sure that you’ll love them, that I’m giving away another 3 discount vouchers that give you 10% off the retail price. All you need to do is sign up for the Malt Blue mailing list and either drop a comment, or tweet us with the hashtag #cornerstone2 and you’re in with a chance.

The first 3 people to do so will get the discount. I’ll let you know you’ve won by email.

If you liked what you read and would like to see more, please retweet it, or give it a like on Facebook or even give it some Digg love. And we always value you feedback and comments.

Matt's Pic About Matthew Setter

Matthew Setter, a passionate Australian, is the founder and chief-editor of Malt Blue. Follow him on Twitter at @maltblue, join in the discussion on Facebook and find out more about him on the team page.

  • kris meister

    Wow, and to think I’ve been using Cornerstone for 4 months and have been badmouthing it for not having  a BLAME button.
    The buttons below the code window are super cryptic not to mention tiny. I’m certain many people do not notice these.

    • maltblue

      @kris meister really? That’s a little funny. Cornerstone’s a really solid tool I find. Maybe the buttons are a bit cryptic and worth an email to them saying such. As a result, in the next version, they may become more prominent. I’m glad the post could help you out.

  • devios1337

    Wow I had no idea this feature even existed! Why is it hidden under such a tiny inconspicuous button and not enabled by default?!