Visualising Subversion with Gource

Over the weekend I stumbled across a video link, released (I assume) by Flickr. The video is a visualisation of the last 7 years of commits into the Flickr Subversion repository. Wow, there’s a lot of work been done to Flickr over the past 7 years! What’s even more interesting is you can easily create the same type of visualisation with your own project using an open-source project called Gource.

Gource is a version control visualisation tool developed by Andrew Caudwell. At the moment it supports Git, Mercurial and Bazaar but it is also possible to use it with Subversion (SVN) with a few extra steps. I’ve created a video for a project I’ve been working on with another developer for 9+ months. The video isn’t as active as the Flickr one but its still interesting to watch and see how a project develops right before your eyes.

Gource Visualisation from Matt Hobbs on Vimeo.

The videos produced by Gource really illustrate how much work goes into projects over time, with each developer ‘shooting a laser’ at each file created / changed / deleted. Files in the same folder are clustered together, lines in-between these clusters link them together depending on the folder structure.

Creating the videos is fairly simple, I’ll give you a step by step guide how to do it using an SVN repository below. You will need:

First you will want to grab a copy of Gource and extract the zip file to somewhere easily accessible. I’ve used ‘c:\gource’ as you will be using the command line so it’s simple to find. Extract Python into a similar directory, I used ‘c:\python31′. If you don’t have the SVN command line client installed, install it and note down where it’s installed too.

Next you need to export the SVN repository log file to an XML document. To do this open a command prompt and locate the SVN client directory. Now type:

svn log http://www.yourrepository.url/svn/ --verbose --xml > projectlog.log

This command has exported the SVN log file to an XML doc that you should see in your SVN client directory. Since Gource doesn’t support SVN natively, the log file needs to be converted into a format Gource will understand. To do this copy the XML log file and this python script into the python directory. To convert the log file type the following from the command line in the python directory:

python --filter-dirs projectlog.log > my-project-gource.log

Great! Now time for the fun part! You now have a log file (my-project-gource.log) that Gource can understand, so copy it to the Gource directory and bring up the command line. To generate the video created above I used the following command line:

gource --log-format custom my-project-gource.log -s 0.1 --hide filenames --stop-at-end --disable-progress -1280x720 -f --disable-progress --hide date

The command line is pretty self explanatory, I’ve set the size of the video I want, and hidden a few elements that weren’t needed. The “-s 0.1″ is an important command as it sets how quickly the visualisation runs through the log file. It’s worth experimenting with different values until you are happy with the results.

If you look in the README.TXT file thats in the Gource directory it gives you a whole list of options that are available to experiment with, there’s hours of fun in there if you really want delve into Gource.

Saving the video

This part actually took me longer to complete than generating the video in Gource; due to a few video encoding issues I was having (Grr!). Capturing the video is simple (once you know how) and uses a program called Fraps. Fraps is usually used in the online gaming scene, it is used to capture full-screen video and save it into an (uncompressed) video format. Once installed it will sit in your taskbar waiting for a full-screen video to kick in which it can then capture.

Play your Gource video from the command line in full-screen and press F9, this is the hotkey that triggers Fraps to start recording. Once complete, your video will be saved into the ‘\fraps\movies’ directory. The video that has been saved is in an uncompressed format so it’s likely it will be a large file (mine was around 700MB for 2 mins at 1280 x 720). This size isn’t very practical so it’s time to convert it to a smaller more portable format. For this we use the excellent VirtualDub by Avery Lee.

Once VirtualDub is installed it only takes a couple of steps to compress the video down:

  1. Run VirtualDub and open your Fraps video file
  2. From the Video menu select ‘Compression…’
  3. Choose the codec / compression settings you wish to use (I used the XviD codec single pass)
  4. From the file menu select ‘Save as AVI…’, once compressed you are done!

As simple as that! The file produced will be much smaller which you can then upload to Youtube / Vimeo as you see fit. Gource may not have a huge number or practical uses other than eye candy, but it’s a superb little tool that I will be using again in the future.