/gource-visualizer

name: gource-visualizer
description: >
  Produce animated source control visualizations using Gource. This skill
  handles installation of Gource and ffmpeg, detection of repository metrics,
  preset-based configuration, single and multi-repo log generation, ffmpeg
  video encoding pipeline, headless rendering for server environments, caption
  generation from git tags, GitHub avatar resolution, and GSD output delivery.
  Use this skill whenever the user wants to visualize repository history,
  create a code evolution video, see project timeline animations, generate
  Gource videos, combine multiple repos into one visualization, or produce
  any kind of source control visualization. Also trigger when the user mentions
  "Gource", "repo visualization", "code history video", "project evolution
  animation", or asks to "show me what we built".

Gource Visualizer

Gource is an open-source software version control visualization tool that renders repository history as an animated tree. This skill orchestrates the full pipeline from installation through rendering, producing MP4 or WebM video files, PNG thumbnails, and render summary reports. It activates when a user wants to visualize repository history, create a code evolution video, generate a Gource animation, see project timelines, or says "show me what we built."

All script paths below are relative to `skills/gource-visualizer/`.

Quick Start

The 80% case: a single git repository, one video output.

1. **Install dependencies** (idempotent -- skips if already present):

   bash scripts/install-gource.sh

2. **Detect repository metrics** -- captures commit count, contributors, date range as JSON:

   bash scripts/detect-repo.sh <repo-path>

3. **Select a preset** based on user intent (default: `standard`):

• "quick look" / "preview" --> `quick`
• "presentation" / "demo" --> `standard`
• "publication" / "YouTube" / "portfolio" --> `cinematic`
• "thumbnail" / "screenshot" --> `thumbnail`

4. **Render the video**:

   bash scripts/render-video.sh --repo <repo-path> --preset standard --output <output-dir>/video.mp4

The render script auto-calculates `--seconds-per-day` from repository metrics and preset target duration. It auto-detects headless environments and delegates to `scripts/render-headless.sh` when no display is available.

5. **Deliver output** to the user with a summary: video file path, duration, resolution, file size, repository metrics (commits, contributors, date range).

Decision Tree

Route user intent through this tree to select the right workflow path.

User wants a visualization
  |
  +-- Single repo in current directory?
  |   +-- Yes --> Quick Start path (above)
  |   +-- No  --> Ask which repo, or detect workspace repos
  |
  +-- Multiple repos mentioned?
  |   +-- Yes --> Multi-Repository Workflow (below)
  |
  +-- Specific time range mentioned?
  |   +-- Yes --> Add --start-date YYYY-MM-DD --stop-date YYYY-MM-DD
  |
  +-- Quality or purpose mentioned?
  |   +-- "quick look" / "preview"              --> preset: quick
  |   +-- "presentation" / "demo"               --> preset: standard
  |   +-- "publication" / "YouTube" / "portfolio" --> preset: cinematic
  |   +-- "thumbnail" / "screenshot"            --> preset: thumbnail
  |
  +-- No display / CI / server environment?
      +-- Auto-detected by render-video.sh; --headless flag added automatically

Multi-Repository Workflow

Combine multiple repositories into a single visualization with namespace prefixing and optional per-repo color coding.

1. Collect repository paths from the user. 2. Merge logs with color coding:

   bash scripts/merge-repos.sh --color --output combined.log <repo1> <repo2> ...

3. Render the combined log:

   bash scripts/render-video.sh --repo combined.log --preset <preset> --output <output-dir>/video.mp4

For detailed multi-repo configuration (namespace prefixing, color palette, chronological sorting), see `references/multi-repo-guide.md`.

Enhancement Options

Optional enhancements to add to any render command:

• **Captions** (milestone markers from git tags):

  bash scripts/generate-captions.sh <repo-path> captions.txt

Then pass `--caption-file captions.txt` to `render-video.sh`.

• **Avatars** (GitHub profile pictures for contributors):

  bash scripts/resolve-avatars.sh <repo-path> avatars/

Then pass `--avatar-dir avatars/` to `render-video.sh`.

• **Logo overlay:** `--logo path/to/logo.png`

• **Title overlay:** `--title "Project Name"`

• **Custom time range:** `--start-date YYYY-MM-DD --stop-date YYYY-MM-DD`

• **WebM format:** `--format webm` (VP9 codec instead of H.264)

• **Audio track:** Post-process with ffmpeg to add music (see `references/ffmpeg-pipeline.md`).

Preset Reference

| Preset | Resolution | FPS | Use Case | Target Duration | |--------|-----------|-----|----------|-----------------| | quick | 720p (1280x720) | 30 | Fast preview, iteration | ~30s | | standard | 1080p (1920x1080) | 60 | Presentations, demos | ~3 min | | cinematic | 1080p (1920x1080) | 60 | YouTube, portfolio, publication | ~4 min | | thumbnail | 1080p (1920x1080) | -- | Single frame capture | < 10s |

Preset configs are at `configs/preset-<name>.conf`. The render script auto-calculates `--seconds-per-day` to hit the target duration based on repository date range.

For preset customization and parameter details, see `references/presets.md`.

Reference Documents

| Reference | When to Read | Purpose | |-----------|-------------|---------| | `references/installation-guide.md` | Installation fails or platform-specific issues | Detailed platform install procedures (apt, brew, manual) | | `references/presets.md` | User wants to understand or customize presets | Preset breakdown, parameter tuning, config format | | `references/ffmpeg-pipeline.md` | Video encoding issues, format conversion, audio