# Gource — Animated Software Version Control Visualization

> An open-source tool that renders animated visualizations of version control repository history, showing files, directories, and contributors as a real-time tree that grows and evolves over time.

## Install

Save as a script file and run:

# Gource — Animated Software Version Control Visualization

## Quick Use
```bash
# Install on Ubuntu/Debian
sudo apt install gource
# Run in a Git repository
cd my-project && gource
# Export to video
gource -1920x1080 -o - | ffmpeg -y -r 60 -f image2pipe -vcodec ppm -i - -vcodec libx264 output.mp4
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-c6a700aa
Author: Script Depot