Back to Blog
December 16, 2020

Visualizing Git Repositories

Learn how to create stunning git visualizations using Gource and FFmpeg. A step-by-step guide to visualize repository history for top GitHub projects.

TLDR: These are the high level steps to create visualizations for your own Git repositories.

  • Use Gource for creating the git visualization PPM frames
  • Use FFmpeg for converting PPM frames to MPEG/AVI (any codec) of your choice
  • Use combination of sox and FFmpeg to add background music to the generated video (Optional)

Introduction

The side-project I did was to create the git visualizations for top 100 starred projects in GitHub. Aim is to provide an End of Year update for 2020 for the aforementioned open-source projects.

This seemed a trivial task but, boy o' boy, I struggled to get this working properly. So, let's go through each step in detail below:

Step 1: Gource | FFmpeg | sox

Download and install Gource, FFmpeg and sox (optional) on your OS of choice. For FFmpeg and sox, the binary has to be added to path but steps should be relatively easy. Gource puts the binary in path automatically but if it doesn't, just add the binary directory to the path manually.

Step 2: Clone Repo Of Choice

Clone the GitHub repo you want to create the visualizations of. (Ex. Kubernetes)

git clone https://github.com/kubernetes/kubernetes.git

Step 3: Run Gource and FFmpeg

To generate the video: cd into the cloned directory and run the command:

gource --hide filenames,dirnames,usernames,progress,mouse --font-size 20 --seconds-per-day 0.1 --auto-skip-seconds 1 -1920x1080 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 -preset ultrafast -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 kubernetes.mp4

Step 4: Prepare Audio to be mixed (Optional)

This was the first hurdle as my audio length was shorter than the video length and I wanted to loop the audio till the length of my video. I used sox to create a new mp3 file with an input mp3 looped 5 times:

sox input_music.mp3 looped_output_music.mp3 repeat 5

Step 5: Do the actual music mux (Optional)

FFmpeg has a nifty feature where you can mux the audio and video with a flag (shorter) that will clip the audio where the video ends:

ffmpeg -i kubernetes.mp4 -i looped_output_music.mp3 -shortest final_video.mp4

Orchestration Challenges

The above process will help you in generating the visualization for a single repository. But, my use case was to generate it for top 100 repositories. I solved it by creating a bunch of shell scripts triggered by cron:

  • One off script - retrieve top 100 repository urls and clone everything in a folder
  • Recurring - take 10 repository batch and generate raw Gource video
  • Recurring - take the raw files one by one and mix it with randomly selected mp3 from a folder

Hope you find it useful. Please message me if you need any help, I'll try my best to solve it for you.

Back to all posts