On the Forgetting of Gource

Alright.  This is the very last time I figure out how to get gource producing visualisations of my development activities from scratch. Today’s post is me leaving notes on this for next time, so I can cut straight to the chase.

A couple of times now, I’ve had occasion to want to give the people I write software for some insight into what I’ve been doing. This project last completed was one such example. A lot of work was done under the hood to enable the code-base to have a replaceable user-interface, and possibly also spatial database. The user-interface had a few new features, but the lion’s-share of it ‘looks’ exactly the same as it was when I started.

I can guarantee you though, that the source looks absolutely nothing like how it started out. Most of my time was spent in taking a code-base “designed” to be a single-user desktop application, and turn it into something that would be relatively easy to make multi-user (it is, now) and optionally, web-enabled (one particular large data-set stops this from progressing just yet).

How then, do I convince the people paying me to tear up their code-base that even though the user-interface is the same, things are now radically different under the hood? Enter gource, and some discussion on how it visualises the git repository as the source-code evolves through the project.

No more re-learning how to do this from vague memory. It’s time to let the sillibrain remember for me, and just remember that I once wrote about it in this post.  In faffing about with just the right command-line settings, I’ve settled on the following for getting the kind of visualisation I like most:

gource -1280x720 --seconds-per-day 1 --auto-skip-seconds 2 --font-size 18 --file-idle-time 0 --title "MWRD Development History" --key <RepositoryPath>

Some reasoning on the settings below:

  • The resolution chosen is what Youtube considers 720p (or ‘high definition’).  Render’s nice on the web, see?
  • seconds-per-day = 1
    • salt to taste, I tend to keep it very small because the novelty factor in this seems to be a single-shot thing.  I’ve never had anyone ask to see it twice, for instance.
    • Don’t let it drag on until they get bored, and don’t do this unless there’s a story you need to tell that’s bigger than “Isn’t this cool?”.
  • Auto-skip-Seconds of 2:
    • That’s just long enough for me to notice a pause, accompanied by a jump in dates. Again, salt to taste.
    • The things I’ve been building lately tend to be more on the agile side of the tracks. That means a number of sprints, with breaks in-between.
    • Which also means a number of longish pauses in commit-history.  Long pauses in the presentation can leave an impression of “Here I am, twiddling my thumbs… again…”, so don’t go there.
  • File-idle-time of 0:
    • There’s very little visual difference between a massive refactoring cutting deep into a source-tree, and a time-out on source-file changes on that same tree causing the files to “disappear”, when they’re still actually there in the repository.
    • Saves on those pesky questions like “That entire branch just vanished! Did you delete all that stuff we wanted kept?”
  • The rest fall more into situational aesthetics. Again, salt to taste.

I capture the output with FRAPS, which seems to work better than CamStudio for this kind of video.  The default output AVI file is huge. With a little editing, very similar quality video for a much smaller file footprint is possible. The raw video below started out at close to 960 Mb.  Way too large for what it is.

To shrink it for hosting at Youtube as per their encoding preferences, I pull out avidemux for Windows (substitute recordmydesktop and PiTiVi for a Linux build environment). Using the preferred video codec, I can drop that file size down to about 35 Mb with no visible loss of quality.

Avidemux Youtube Settings

Avidemux Youtube Settings

And there we go.  Notes on my gource preferences, and detail on getting the resulting video capture file-size small without visible loss of quality.  Here’s the end-result (view in 720p quality for best results):

Disclaimer:  No, I haven’t actually walked the client through this visualisation. And yes, I view it as very optional eye-candy.

The acceptance testing phase was quieter than I thought it would be, so I took a very rough-cut attempt from earlier in the project, and polished. Seemed  more fun than just thumb-twiddling whilst waiting for the bug-hammer to fall.  If the client never raise the issue of how far I got in enabling the code-base for a Web UI,   the visualisation above will only see an audience via this blog post.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s