How to use Gource to visualize your code repos (and more)

Why settle for boring numbers and static graphs to describe your open source project when you can dynamically display the movements and activity within your project? Gource is an amazing and flexible tool that can be used to display activity from your repositories using a video visualization that people love. Gource can be redistributed and modified under the terms of the GNU General Public License (version 3 or later). Here are a few interesting videos of how other people have used Gource, which might help you think about how you might use it:

Yum Gource visualization

The Yum Gource Visualization video is a tribute to Seth Vidal, lead developer of the Yum project and long-time Fedora contributor, shortly after he was killed by a hit-and-run driver while cycling. Seth's contributions to Yum are in blue, whereas contributions from others are in white.

Linux kernel development

Linux Kernel Development, 1991-2015 shows how Gource can help you visualize the full development history of any open source project (the Linux kernel, in this example).

Population dynamics

Population Dynamics 1970-2010 offers a visualization of population dynamics.

With any flexible and customizable tool comes a dizzying array of options and configurations. For example, I used the command below to generate a visualization of the MailingListStats (mlstats) repository from the Metrics Grimoire suite of tools:

$ gource -f --logo images/bitergia_logo_sm.png --title "MailingListStats AKA mlstats" --key --start-date '2014-01-01' --user-image-dir images -a 1 -s .05 --path ../MailingListStats

And here is the video generated using these options:

Option Details:

• --path /path/to/repo (or omit and run Gource from the top level of the repo dir)
• -f show full screen
• --logo images/bitergia_logo_sm.png
• --title "MailingListStats AKA mlstats"
• --key (shows color key for file types)
• --start-date '2014-05-01'
• --user-image-dir images (Directory with .jpg or .png images of users - ‘Full Name.png' for avatars)
• -a 1 (auto skip to next entry if nothing happens in x seconds – default 3)
• -s .05 (speed in seconds per day – default 10)

Gource can also be used to display non-repository information (bug trackers or mailing lists) using the custom log format.

For example, this is how I did a visualization of a mailing list using Gource's custom log format:

• Ran a query on a database created by mlstats with all of the messages from one of the Linux kernel mailing lists.
• Gathered data about each mailing list post, including the person who posted the message, and if it was a reply, which user they were replying to (M - modified thread by replying to it). Otherwise, flag it as a new message (A - added new thread)
• Stripped the emails down to the username (everything before @example.com) to have a shorter identifier for the users, which looks much better for the visualization.
• Formatted the output into a file called gource_output.log, a nice pipe-separated Gource custom log format sorted by time in this format: unixtime|user-email_sender|A|new
unixtime|user-email_sender|M|user-in_response_to
• Ran gource $ gource -i 5 --max-user-speed 100 -a 1 --highlight-users gource_output.log
• Options used:
  • -i 5 Time files remain idle (default 0). This allows people being replied to to disappear after 5 seconds to clean up a bit and make it more readable.
  • --max-user-speed 100 Speed users can travel per second (default: 500). I slowed this down to 100 to make it easier to see the users.
  • -a 1 Auto skip to next entry if nothing happens for a number of seconds (default: 3) sped this up a bit.
  • --highlight-users keeps the usernames for the people sending emails from disappearing. I would have liked to have the same for filenames, which are the people being replied to, but can't seem to find at option for that.

To learn more about Gource, check out the project's Github page or see Dawn speak at LinuxCon in Toronto.

This article offers examples of what Dawn will include her in LinuxCon talk, Visualize Your Code Repos and More with Gource on Tuesday, August 23. At LinuxCon, she will dive into more options and creative ways to use Gource beyond the typical source code visualization. Attendees should walk away from her talk with ideas and techniques for how to create awesome videos showing the activity within open source projects and communities.