Gource Recipe For Win32

I think that a rendered historical view of a source controlled software project can be a key asset in understanding how a piece of software got to be what it is at any point in time.  This seems to me to be a missing first class asset from our general tooling.  Gource provides this as a beautifully rendered video timeline of a software project’s birth and evolution over time.

Here I’ve provided a small sample showing John Resig’s initial commit activity in JQuery’s Git repository.

Most of the documentation and work with Gource appears to be targeted toward *nix.  To the end spreading this love a bit wider into the Windows community, I’ll now share with you my recipe for getting it working in Win32.

1. First you’ll need to get Git working in Windows.  For this I recommend downloading and installing the Full Official Version of MsysGit from its Google code page: http://code.google.com/p/msysgit/downloads/list.  Make sure you install it with the “Git Bash Here” option (see the install options in the wizard).  Also, you should allow the installer to put Git into your PATH environment variable, so that its globally accessible from the command-line.  The default location of  git.exe in Win32 is “C:\Program Files\Git\bin”

2. Next you’ll need Gource.  You can get it from its Google code page: http://code.google.com/p/gource/.  Download the binaries for Windows and place them into a directory at c:\gource.  Manually add this path to your PATH environment variable so that it too is globally accessible.

3. Now in order to save the video output of Gource, you’ll need a video capture program.  For this you can use the free ffmpeg, althrough I was not able to get the ppm output working in Windows to pipe it into ffmpeg.  Thus, I opted for the shareware version of Fraps: http://www.fraps.com/download.php.  Fraps can be used to create a video of any window, including in our case the Gource output.  Also while I have not tried it myself, I suspect that Techsmith’s Camtasia and/or Jing might do the trick nicely also.

4. Next its time to get some source and make a vid.  You can get the source of a Git project by cloning its repository to your local system.

• Create a local folder called c:\src
• In Windows Explorer right mouseclick and choose “Git Bash Here”.  Follow the instructions here: http://kylecordes.com/2008/git-windows-go to get your Git account and public key setup. 
• Clone JQuery’s Git repository by typing into your Bash command prompt the following: git clone http://github.com/jquery/jquery.git.  Now you’ll have a new folder at c:\src\jquery with the jquery project’s src.
• Now to create a video of the project history do the following:
  • Start up Fraps and minimize it to your system tray.
  • open up a new cmd window and type the following command: c:\gource\gource –stop-at-end  c:\src\jquery.  This will start Gource from the beginning of the project’s historical timeline.  You’ll the see the video begin at this point.
  • Finally, with the Gource video window focussed, hit F9 which is Fraps’ default video capture key to get it to begin to capture the Gource output.
  • After Gource finishes, Fraps will save the video to its default video location, which is c:\Fraps\Videos.

Tada!…  Pretty nifty tools.  Gource works with Git, Mercurial, and SVN to date.  I’ve seen a few ppl out there claiming to have it working with TFS also.

See what kind of fun you can have with it..  Go forth and be fruitful..