Gource — Animated Software Version Control Visualization

Introduction

Gource creates animated visualizations of version control repositories. It reads commit history from Git, Mercurial, SVN, or custom log formats and renders a real-time tree where files orbit around directory nodes and contributors appear as avatars making changes. The result is a compelling visual timeline of how a codebase evolved, useful for presentations, retrospectives, and project documentation.

What Gource Does

• Renders an animated tree visualization of repository file structure over time
• Shows contributors as named avatars interacting with files they modified
• Supports Git, Mercurial, SVN, Bazaar, and custom log formats
• Exports frames to a video pipeline for recording MP4, WebM, or GIF output
• Handles repositories with thousands of files and years of history

Architecture Overview

Gource reads the VCS log (or a custom-format log file) and sorts events chronologically. It uses OpenGL to render a force-directed graph where directories are nodes and files are leaf elements connected by branches. Each commit event triggers an animation: the committer's avatar moves to the affected file, the file pulses, and new files bloom into the tree. A camera system automatically zooms and pans to follow activity. The renderer outputs to screen or emits raw PPM frames that can be piped to ffmpeg for video encoding.

Self-Hosting & Configuration

• Install via package manager: apt install gource, brew install gource, or choco install gource
• Run gource inside any Git repository for an instant visualization
• Set resolution and framerate: gource -1920x1080 --seconds-per-day 0.5
• Customize user avatars by placing images in a directory and using --user-image-dir
• Use --hide flags to toggle visibility of filenames, dirnames, users, or the progress bar

Key Features

• Real-time OpenGL rendering with smooth animations and a force-directed layout
• Multi-repository support by merging logs from separate projects into one visualization
• Customizable speed, colors, bloom effects, date range, and file filtering
• Avatar support for showing contributor photos alongside their names
• Caption and title overlay support for annotating the timeline with milestones

Comparison with Similar Tools

• git log --graph — text-based branch graph; Gource produces a full animated spatial visualization
• GitHub contribution graph — shows commit frequency per day; Gource shows file-level changes and contributors spatially
• GitStats — generates static HTML reports with charts; Gource creates an animated video
• Codeflower — static circular visualization of a codebase; Gource adds the time dimension with animation
• Hercules (src-d) — analyzes code ownership statistically; Gource focuses on visual storytelling

FAQ

Q: Can Gource handle very large repositories? A: Yes, though repositories with millions of files may need filtering. Use --file-filter and --max-files to limit scope.

Q: How do I export a video? A: Pipe Gource output to ffmpeg: gource -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 output.mp4.

Q: Does it support monorepos with multiple projects? A: Yes. You can use --path filters or merge custom logs from separate directories to show multiple projects in one view.

Q: Can I customize which files or users appear? A: Yes. Use --file-filter, --user-filter, and --hide to control visibility.

Sources

• https://github.com/acaudwell/Gource
• https://gource.io