I really love Gource and over the years I have refined a simple pipeline to generate some cool feel-good visualisations for the codebases I have involved been with. Here is my formula:

git repo + gource config + user pics dir + captions + logo
=> gource PPM file
run ffmpeg script
=> gource video
add music audio file
=> final VIDEO

Prerequisites

• Download and install the latest Gource binaries.
• Download and install ffmpeg.
• Create a separate directory for your Gource project

Step 1 - Generating the PPM file

The goal of this step is to generate a PPM file, which is a simple of picture dump of all the frames generated by Gource.

This section describes all the parts that are necessary to create that file:

• Git repository you wish to visualise
• Custom user pictures
• Custom logo
• Caption file
• Gource config file to use as follows:

gource --load-config <gource.config file path>

Git repo

• Clone the repository you want to visualise
• From the repo directory run the command git shortlog -sne to generate a list of all the users involved in the repo and save that list in a file

User pictures and logo

• If you want to use custom pictures for users, create a separate users folder in your project folder.
• Using the list generated in the step above download all the corresponding pictures, ensuring that they are named exactly like in than list, using exactly the same casing i.e. if the user is called fOobOrg, the picture must be named fOobOrg.eee where "eee" is whatever extension (png,jpg, gif, bmp etc.)
• Source a logo and save it in your project folder - try to get a transparent background as it will look better.

Caption file

I usually invest a lot of time in producing a meaningful caption file as it helps people get some context around all the pyrotechnics. My recommendation is to use the repository log messages as a starting point.

• Pre-populate a caption file by running the command git log --pretty="%at|%as %s" in the repo working directory and saving its output to a caption.txt file in your project folder. This will generate a good starting point for introducing custom captions. Here is an example caption output:

1471530982|2016-08-18 Fix Unused Default Values Issue (#31)
1471117298|2016-08-13 release 0.6.1.9
...

• Edit the caption file as you see fit, use an online Date to UNIX timestamp converter tool to generate the required timestamp. Make sure your captions is properly sorted in a chronological order.

Gource config file

Gource has many options but I have settled on a few that produce just the right amount of details for my purpose.

I usually try to create 2 videos:

• a short one that uses the overview camera-mode option,
• and a longer one with more details and the tracking camera-mode.

I find that 3-4 minutes maximum is a good length for the short video to keep people engaged as it corresponds to the average duration of soundtracks.

[display]
viewport=1920x1080

[gource]
key=true
start-date=<DATE yyyy-mm-dd>
seconds-per-day=1.25
user-image-dir=<PATH>
colour-images=false
multi-sampling=1
camera-mode=overview
filename-time=2.0
title=<TITLE>
user-scale=1.50
user-font-size=18
stop-at-time=<TIME IS SECONDS>
hide=mouse,progress
highlight-users=1
highlight-all-users=1
path=<REPOSITORY PATH>
output-framerate=60
caption-file=<CAPTION FILE>
caption-size=22
caption-duration=6
logo=<LOGO PATH>

Step 2 - Generating the intermediary video

To generate the intermediary video I use ffmpeg to process the PPM file as follows:

ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i <gource.ppm path> -vcodec libx264 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 <gource.x264.mp4 output path>

Ensure that the frame rate matches the output-framerate option you have used to generate the PPM file.

Step 3 - Producing the final video

To produce the final video, I merge the generated video with an audio file using ffmpeg:

ffmpeg -i video.mp4 -i <audio file path> -c:v copy -c:a aac output.mp4

I usually do not do any further editing or titling as it is not worth the effort.

Next steps

It takes a bit of work to produce a Gource video so there is an opportunity to streamline the process. One way to do this could be to create a helper tool as I describe in my post

A great starter project: a config file generator for Gource

Dinh Doan Van Bien ・ Apr 24 '21

.