Gource: rendering a Git repository as an animated tree

What Gource actually draws, and who it is for

Gource is a visualisation tool for source control repositories. The README describes the model precisely: the repository is a tree, the root sits at the centre, directories are branches, files are leaves, and contributors appear and disappear as they touch specific files and directories. Nothing in that description is a metaphor for a chart. The output is an animation of a tree growing and shedding leaves over commit time.

The audience is narrow and specific. It suits people who need to explain a codebase's history to an audience: a conference talk, an onboarding session, a project retrospective, a video clip. It also suits anyone who wants to see, rather than read, how a long-lived repository's activity clusters around certain directories and certain people. It does not suit anyone who wants numbers. There is no churn report, no author ranking, no diff view. If the question is "how much did this module change last quarter", Gource is the wrong instrument, and the README offers no flag that turns it into the right one.

The display is rendered using OpenGL and requires a 3D accelerated video card. That is a hard requirement stated in the requirements section, not a recommendation. A headless build machine or a virtual machine without GPU passthrough will not produce the animation. This single constraint rules out a large class of CI and server environments before any other consideration applies.

The data flow: from VCS log to animated tree

Gource does not read a repository's object database directly. It reads a log. The --log-command option takes a VCS name from the set git, svn, hg, bzr, cvs2cl and shows the log command Gource uses for that system. The --log-format option takes the same set plus custom, and the README states it is required when reading from STDIN. That is the architectural hinge: Gource is a log consumer with a small set of built-in log parsers, and a custom escape hatch.

This explains several flags that otherwise look arbitrary. --git-branch exists because the git log command Gource runs is branch-sensitive and defaults to the current branch. --author-time exists because a commit carries two timestamps, the author's and the committer's, and the animation's ordering changes depending on which one you pick. --no-time-travel exists because a commit whose timestamp is in the past relative to the previous one would otherwise move the simulation backwards; the flag uses the time of the last commit instead.

Once parsed, entries are placed on a timeline and the simulation advances through it. -s, --seconds-per-day sets the speed in seconds per day; --realtime plays at real speed; -c, --time-scale scales the simulation without changing the timeline, and the README notes this affects the movement speed of user avatars. -p, --start-position accepts a value between 0.0 and 1.0 or the literal random, and --stop-position stops at a position, with the README noting it does not work with STDIN. That last caveat is worth internalising: position-based seeking is a property of a known-length log, and a piped stream has no known length.

Installing Gource and running it on a repository

The repository carries a configure.ac, a Makefile.am, an autogen.sh and an INSTALL file, so the documented build path is the Autotools one. On a Debian-derived system the packages come from the distribution, and the configure step needs the OpenGL and font development headers present before it will succeed. The README specifies that the font is loaded through FreeType and that most font file formats it supports, such as TTF and OTF, work.

sudo apt install gource

With the binary in place, the minimal invocation takes a path. Run it inside a checkout and Gource picks up the repository and starts the animation.

gource

In practice the first run on a real repository is unreadable, because vendored directories, generated files and merge noise dominate the tree. The filter flags are the fix. --file-filter takes a regular expression and removes matching file paths; --file-show-filter does the inverse and keeps only matches. The same pair exists for users as --user-filter and --user-show-filter.

gource ~/src/myproject \
  --file-filter 'vendor|node_modules|\.min\.' \
  --seconds-per-day 0.5 \
  --stop-at-end

What you should see is a tree that grows from the centre, with named contributors appearing at the files they touch. The --stop-at-end flag makes the process exit when the log is exhausted instead of waiting for a keypress. If the animation runs too fast to follow, raise the value passed to --seconds-per-day; the flag is measured in seconds of wall clock per day of commit history, so a larger number is slower. Avatars come from --user-image-dir, a directory of .jpg or .png files named after the contributor, for example "Full Name.png", with --default-user-image as the fallback.

Where Gource stops being the right tool

The most consequential limitation is that Gource has no notion of code. It knows paths, authors and timestamps. A commit that changes one character in a 4000-line file and a commit that rewrites the file entirely produce the same visual event. Anyone hoping to read effort, complexity or risk out of the animation is reading something the tool does not encode.

The second limitation is the log parser boundary. Because Gource consumes a log rather than a repository, anything the underlying log command does not emit is invisible. Renames, for instance, depend entirely on what the VCS log reports and on whether the parser understands it. The README documents --log-format custom without describing the expected custom record shape, so a reader who needs a non-standard source has to go to the source tree rather than the documentation.

The third is the GPU requirement already noted. A remote server, a container without device access, or a laptop with broken drivers will fail before the animation starts, and the README gives no software-rendering fallback.

Finally, there is the presentation problem. A repository with a decade of history and thousands of files produces a dense, fast-moving tree that communicates little to an audience seeing it once. The filtering and speed flags are not optional polish; on any repository of real size they are the difference between a legible clip and visual noise.

Gource against Gephi and the static graph approach

The natural alternative for people who want to see repository structure is a graph tool such as Gephi, fed by an exported co-change or contributor-file network. The difference in approach is fundamental. Gephi lays out a static network and lets you interrogate it: filter by node degree, colour by community, inspect individual edges. Gource animates a timeline and gives you no query surface at all. You cannot ask Gource which files changed together; you can only watch them change.

That makes the two complementary rather than competing, and the choice is about the question. If the question is "which parts of this codebase move together", export a network and open it in a graph tool. If the question is "what did the last three years look like", Gource is the shorter path, because it needs no export step and no layout configuration. It reads the log directly.

Within Gource's own territory the alternative is a screen recording of a code review or a hand-built animation, which is more work and less faithful to the actual commit order. The trade Gource makes is fidelity to the log in exchange for giving up every form of numeric output.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the most recent push recorded is 2026-03-06, the same day as the gource-0.56 release. The previous release, gource-0.55, is dated 2024-06-17, and gource-0.54 is dated 2023-01-19. The release cadence is therefore irregular: roughly eighteen months between 0.54 and 0.55, and about twenty months between 0.55 and 0.56. That pattern matters for anyone pinning a version. A bug fixed after a release may sit unreleased for a long time, and building from master is the only way to get it.

Gource is licensed GPL-3.0, with the licence text in the COPYING file at the repository root. The practical consequence for most users is unremarkable: running the binary to produce a video for a talk or an internal presentation does not create a distribution obligation. Distributing a modified binary, or shipping Gource inside a product, is where the copyleft terms start to bind, and that is a question for a lawyer rather than for this article. The repository also carries a .gitmodules file, so a clone should use --recursive if you intend to build from source; the INSTALL file is the place to check the exact build sequence.

Upgrade cost is low in normal use. The options in the README are long-form flags with stable names, and no deprecation notices appear in the documented option set. The realistic upgrade risk is not the CLI but the build: OpenGL and FreeType are external dependencies, and a distribution that moves either one can break a source build independently of anything Gource changes.

Editorial conclusion

Adopt Gource if you need a short, legible animation of who touched which paths over a period, and you have a machine with a 3D accelerated video card and a repository whose history survives filtering. Do not adopt it if you want metrics, blame, churn numbers or a report you can diff between releases; the tool draws a tree and exits. Before committing to it for a talk or a video, verify three things on your own history: that the default git log command it runs produces a timeline you recognise, that --file-filter removes the vendored and generated paths your repository carries, and that --stop-at-end or --stop-at-time actually terminates the run on your platform rather than leaving a window open. The README documents the flags but not the failure modes, so the check is yours to run.

Frequently asked questions

Official sources

1. acaudwell/Gource on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases