Producing your own git repository animated visualization video

Have you seen the gource video visualizations of git repositories? Gource lets you create beautiful animated tree visualizations of git repos, with the root directory at the centre, other directories as branches and files as leaves. There are also representations of the different programmers contributing to the project over time. Creating such video visualizations on mac OS, is really very simple, let me talk you through it:

First we need to install gource:

brew install gource

Be patient, it’s about a 600MB download.

If you have any problems during installation, just update and upgrade you brew:

brew update
brew upgrade

Now go to the git repository root dir and just run:

gource

You’ll see a visualization of all file changes in the current git branch.

If you want to save the visualization as a video, you need to install the ffmpeg library:

brew install ffmpeg

Check the health of ffmpeg:

ffmpeg

You’ll see the current version of ffmpeg.

Now you can run gource with a parameter that allows you to save the visualization as a video file:

gource -s 2 -a 1 ./ -1920×1080 -o – | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i – -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 gource.mp4

Running that command, your video file will be created only in repo, don’t forget to move the video file from repo or use the absolute path for the output file name instead of “gource.mp4”.

The process of rendering is long and slow (1920×1080 and 60fps).
In the example below, I’ve supposed we’re creating a visualization of a repository for a simple, one day project with some support lasting 1 month. The rendering process in that case took 10 minutes. The resulting video is 47 seconds long and 950.5MB in size.

In the previous command we used various parameters to make the video exactly as we wanted it. You can view a full list of available parameters and other helpful examples in the gource repo description.

It allows us to scale time in videos, add a logo overlay onto videos, add our own audio stream from file and many many other features.

Have fun experimenting to get it exactly as you want!

Here’s an example of the the sort of visualization video resulting from the scenario above:

And here’s a (very fast) example of a much larger repository visualization:

Enjoy!