If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/acaudwell/Gource shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2mo ago
• 13 active contributors
• GPL-3.0 licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live acaudwell/Gource repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/acaudwell/Gource.

What it runs against: a local clone of acaudwell/Gource — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in acaudwell/Gource | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 94 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of acaudwell/Gource. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/acaudwell/Gource.git
#   cd Gource
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of acaudwell/Gource and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "acaudwell/Gource(\\.git)?\\b" \\
  && ok "origin remote is acaudwell/Gource" \\
  || miss "origin remote is not acaudwell/Gource (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.cpp" \\
  && ok "src/main.cpp" \\
  || miss "missing critical file: src/main.cpp"
test -f "src/gource.cpp" \\
  && ok "src/gource.cpp" \\
  || miss "missing critical file: src/gource.cpp"
test -f "src/gource_settings.cpp" \\
  && ok "src/gource_settings.cpp" \\
  || miss "missing critical file: src/gource_settings.cpp"
test -f "src/formats/git.cpp" \\
  && ok "src/formats/git.cpp" \\
  || miss "missing critical file: src/formats/git.cpp"
test -f "src/dirnode.cpp" \\
  && ok "src/dirnode.cpp" \\
  || miss "missing critical file: src/dirnode.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 94 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~64d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/acaudwell/Gource"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gource is an OpenGL-based real-time visualization tool that renders source control repository history as an animated tree, where the repository root is the center, directories are branches, and files are leaves, with contributors appearing and disappearing as they edit files. It transforms version control logs (Git, SVN, Mercurial, Bazaar) into a mesmerizing animated visualization that shows project evolution and team activity over time. Classic single-binary C++ project with modular structure: cmd/ contains the CLI entry point (gource, gource.cmd for Windows); data/ holds all assets (shaders in data/shaders/, fonts in data/fonts/, images); src/ likely contains core rendering and VCS parsing logic (not listed but inferred). Build uses GNU Autotools (configure.ac, m4/ macros for Boost/GL detection) with Makefile.am for compilation, and qmake alternative (gource.pro) for Qt-based builds.

Software engineering teams, open-source project maintainers, and technical presenters who want to visualize repository growth, contributor patterns, and project evolution for talks, documentation, or repository analysis. Particularly useful for creating compelling demo videos and understanding large project histories at a glance.

Gource is mature and actively maintained. The codebase is 499K+ lines of C++ (primary language), uses established autotools-based build system (configure.ac, Makefile.am), includes proper versioning (ChangeLog, COPYING, THANKS), and has a dedicated website (gource.io). Recent activity and cross-platform support (Windows .cmd scripts, macOS high-DPI handling, NSIS installer) indicate active development with production-quality tooling.

Low risk for a visualization tool. Primary risk is tight OpenGL/graphics dependency (requires 3D accelerated video cards per README) making it platform-sensitive; codebase uses Boost libraries (filesystem) and GLSL shaders which require careful driver compatibility. Single-maintainer concern (acaudwell) is typical for creative tools. No evidence of comprehensive automated test suite in file listing suggests manual testing burden.

Cannot determine from file listing alone, but project structure suggests active cross-platform maintenance: recent additions of --high-dpi flag (macOS support), frameless window option, and transparent background (for video capture), plus Windows 64-bit build infrastructure (dev/bin/build_win64.pl). Presence of .github/FUNDING.yml indicates GitHub sponsorship setup.

git clone https://github.com/acaudwell/Gource.git
cd Gource
./autogen.sh
./configure
make
./cmd/gource /path/to/repo

Daily commands:

# After build completes:
./cmd/gource
# For specific repository:
./cmd/gource /path/to/git/repo
# Common options:
./cmd/gource --windowed -1920x1080 --seconds-per-day 0.1 /path/to/repo

• src/main.cpp — Entry point for the application; initializes the Gource visualization engine and command-line argument parsing.
• src/gource.cpp — Core visualization engine that manages the tree rendering, file/directory nodes, and animation loop for the VCS repository display.
• src/gource_settings.cpp — Configuration and settings management; parses all command-line options and applies user preferences to the visualization.
• src/formats/git.cpp — Git log parser; converts git commit history into internal action/node objects that drive the visualization.
• src/dirnode.cpp — Directory tree node representation; manages hierarchical file system structure and spatial layout for visualization.
• src/pawn.cpp — User/contributor avatar rendering; represents developers as visual entities moving through the tree during commits.
• src/logmill.cpp — Abstract log processing pipeline; orchestrates parsing of multiple VCS format logs into a unified action stream.

Add Support for a New Version Control System

1. Create a new format parser in src/formats/newvcs.cpp implementing the log parsing logic for your VCS (src/formats/newvcs.cpp)
2. Create corresponding header src/formats/newvcs.h with class declaration inheriting from commitlog base interface (src/formats/newvcs.h)
3. Register the new format in src/logmill.cpp by adding detection logic and instantiation (src/logmill.cpp)
4. Add command-line option handling in src/gource_settings.cpp to expose VCS-specific flags (src/gource_settings.cpp)
5. Test parsing by running gource with your repository and verifying log output (src/formats/commitlog.cpp)

Add a New Interactive Command to the Shell

1. Define the command handler in src/gource_shell.cpp in the command processing switch/case (src/gource_shell.cpp)
2. Add keyboard mapping in src/key.cpp to trigger the command on user input (src/key.cpp)
3. Implement the corresponding action on the main Gource instance via gource.cpp methods (src/gource.cpp)
4. Add visual feedback (caption/text) in src/caption.cpp to confirm command execution (src/caption.cpp)

Add a New Visual Effect or Rendering Pass

1. Create shader files in data/shaders/ for vertex and fragment shader implementation (data/shaders/)
2. Create a C++ effect class (e.g., src/myeffect.cpp) that loads and manages the shader (src/bloom.cpp)
3. Integrate the effect into the render loop in src/gource.cpp by calling it at the appropriate stage (src/gource.cpp)
4. Add command-line flag in src/gource_settings.cpp to enable/disable the effect (src/gource_settings.cpp)

• OpenGL + GLSL Shaders — Hardware-accelerated 3D rendering for smooth real-time visualization of large repository trees; required for visual effects (bloom, shadows) and efficient geometry batching.
• C++ with STL — Performance-critical visualization engine; direct memory control and minimal overhead for animation loops and spatial queries on the file tree.
• Multiple VCS format parsers (Git, SVN, Hg, Bzr, CVS) — Enables visualization of repositories regardless of version control backend; pluggable format system allows users to analyze any VCS-managed codebase.
• Autotools build system (configure.ac, Makefile.am) — Cross-platform compatibility (Linux, macOS, Windows); handles dependency detection and platform-specific build flags.

• Real-time log parsing vs. pre-computed format conversion

  • Why: Gource parses live VCS logs at startup rather than requiring external format conversion steps.
  • Consequence: Simpler user workflow but parsing can be slow for very large repositories (100k+ commits); users may need to pre-filter logs.

• Interactive shell mode vs. pure playback visualization

  • Why: Gource supports interactive commands (pause, seek, filter) during playback for exploration, not just linear animation.
  • Consequence: Added complexity in state management but enables deeper repository exploration; playback is not strictly deterministic.

• Custom tree layout algorithm vs. standard force-directed layout

  • Why: Gource uses a radial/hierarchical tree layout rooted at repository center to visually represent directory structure.
  • Consequence: Intuitive for understanding repository organization but less flexible for non-hierarchical data; layout is tree-specific.

• Single-threaded render loop with synchronous log parsing

  • Why: Simplifies state management and avoids complex synchronization between parsing and rendering threads.
  • Consequence: Large repository parsing can block visualization startup; no real-time log tail for live repositories.

• Real-time monitoring of live repositories (requires parsing at startup, not streaming)
• Web-based or remote visualization (native desktop OpenGL application only)
• Collaborative/multi-user annotation of repository history
• Integration with IDE plugins or VCS GUIs (standalone tool)
• Handling encrypted or access-controlled repositories (requires pre-authenticated VCS access)

OpenGL driver compatibility is version-sensitive (requires GL 2.0+); GLSL shader compilation can fail silently on some platforms. Boost library version mismatches (especially filesystem) can cause build failures — configure.ac uses AX_BOOST_BASE macros that require matching versions. Font rendering depends on FreeType library not always pre-installed (data/fonts/ has TTF but font system integration is implicit). SVN/Mercurial/Bazaar parsing relies on those VCS tools being installed and in PATH. --high-dpi flag on macOS requires SDL2 >= 2.0.1. No visible environment variable documentation — some paths may require $LD_LIBRARY_PATH or similar on Linux.

• Scene Graph Rendering — Gource renders a hierarchical tree structure (files, directories, users) as an OpenGL scene graph where each node's position updates in real-time; understanding scene graphs is essential to modifying the visualization layout algorithm
• GLSL Shader Effects (Bloom Filter) — The bloom effect in data/shaders/bloom.frag uses multi-pass Gaussian blur to create the glowing visual signature; modifying visual effects requires GLSL shader expertise
• Version Control Log Parsing — Gource must parse heterogeneous VCS formats (Git, SVN, Hg, Bazaar) into a unified timeline; understanding log format normalization is critical for adding new VCS support
• Real-time Animation State Machine — Contributors appear/disappear, files move through tree positions, and time advances at variable speeds; the core loop manages animation state transitions and interpolation
• Autotools Build System (Autoconf/Automake) — Gource uses configure.ac and Makefile.am for cross-platform compilation; understanding M4 macros (m4/ax_*.m4) is essential for fixing build issues on new platforms
• Off-screen Rendering & Frame Buffering — Gource supports video output and --transparent background, requiring framebuffer objects (FBOs) and offscreen rendering to capture frames; essential for understanding video export pipeline
• High-DPI Display Scaling — The --high-dpi flag handles macOS/modern Windows DPI scaling where window coordinates differ from pixel coordinates; critical for cross-platform UI correctness

• gitpython-developers/GitPython — Git repository parsing library in pure Python; Gource uses native Git parsing, but this shows alternative approach for VCS log extraction
• mbostock/d3 — D3.js is the standard for web-based repository visualization; Gource is OpenGL desktop equivalent with real-time animation capabilities
• pytorch/glow — Similar GPU-accelerated visualization approach; shows GLSL + OpenGL patterns for high-performance graphics in C++ projects
• stefanw/python-svn — Complements Gource by providing SVN Python bindings for log extraction; Gource's SVN parser (contrib/svn-gource.py) depends on similar log format understanding
• libgit2/libgit2 — Low-level Git C library that Gource could use for more robust Git log parsing instead of shelling out to git command

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for src/formats/ parsers (apache, bzr, commitlog)

The repo has multiple VCS format parsers in src/formats/ (apache.cpp, bzr.cpp, commitlog.cpp) but no visible test suite. These are critical for correctness since they parse repository data. Adding tests would catch regressions when parsers are modified and make contributions safer.

• [ ] Create src/tests/ directory structure
• [ ] Add unit tests for src/formats/commitlog.cpp covering valid/invalid log formats
• [ ] Add unit tests for src/formats/apache.cpp and src/formats/bzr.cpp with sample VCS output
• [ ] Integrate tests into Makefile.am build system
• [ ] Document test running instructions in README.md

Add GitHub Actions CI workflow for multi-platform builds

The repo has dev/bin/build_tar.pl and dev/bin/build_win64.pl scripts for building releases, but no automated CI. A GitHub Actions workflow would catch build failures early across Linux/macOS/Windows and ensure the build scripts stay functional with dependency changes.

• [ ] Create .github/workflows/build.yml with matrix for Linux (autotools), macOS (autotools/Xcode), Windows (MSVC/MinGW)
• [ ] Test against m4/ macro dependencies (ax_boost_base.m4, ax_check_gl.m4, etc.)
• [ ] Add workflow to run autogen.sh && configure && make
• [ ] Include artifact upload for built binaries on release tags
• [ ] Document CI status badge in README.md

Add shader documentation and refactor src/shaders/ module structure

The repo has GLSL shaders in src/data/shaders/ (bloom.frag, bloom.vert, shadow.frag, shadow.vert, text.frag, text.vert) but no documentation of what each shader does or how they're used. Adding shader documentation and creating a dedicated shader loading/management module would improve maintainability for graphics contributors.

• [ ] Create data/shaders/README.md documenting each shader's purpose and parameters
• [ ] Create src/shaders/ directory and add shader.cpp/.h for unified shader loading/compilation
• [ ] Refactor src/bloom.cpp and src/caption.cpp to use centralized shader management
• [ ] Add error handling and GLSL version compatibility checks in shader loading
• [ ] Update THANKS file and ChangeLog if adding new shader abstractions

• Add unit tests for VCS log parsers: The contrib/svn-gource.py shows log format, but there's no visible test suite (tests/ directory missing). Create test fixtures for Git, SVN, Hg logs in src/tests/ and add test targets to Makefile.am.
• Document shader parameters: The bloom.frag and shadow.frag in data/shaders/ have no comments explaining parameters like blur radius, intensity, or sampling patterns. Add comprehensive GLSL comments and create docs/SHADERS.md explaining effect tuning.
• Implement --config-file option: Users must type long command lines (--seconds-per-day, --auto-skip-seconds, viewport); add INI/TOML config file support with ~/.gource/config and per-project .gourcerc files, parsing in main CLI handler.

Gource is a visualization tool with moderate security posture. The primary concerns are around command injection in VCS parser modules, potential buffer overflows in C++ file/directory handling code, and unsafe script execution in build/utility scripts. The codebase lacks visible hardcoded credentials or obvious SQL injection risks. Recommended actions: (1) Audit all VCS command invocations with input validation, (2) Review C++ string handling with static analysis tools, (3) Apply security flags during compilation, (4) Harden Perl/Python scripts with taint checking and input validation.

• Medium · Potential Command Injection in VCS Format Parsers — src/formats/*.cpp files (git.cpp, svn.cpp, hg.cpp, bzr.cpp, cvs-exp.cpp, etc.). The codebase contains multiple VCS format parsers (git, svn, hg, bzr, cvs) in src/formats/ that may execute external commands to retrieve repository history. Without proper input validation and sanitization, these could be vulnerable to command injection attacks if processing untrusted repository data or user-supplied paths. Fix: Implement strict input validation on all repository paths and VCS command parameters. Use allowlists for acceptable characters, avoid shell execution where possible, and use direct API calls instead of spawning shell processes. Apply proper escaping if shell invocation is necessary.
• Medium · Potential Buffer Overflow in File/Directory Processing — src/dirnode.cpp, src/file.cpp, src/action.cpp. The codebase processes arbitrary file paths and directory structures from version control systems (dirnode.cpp, file.cpp). C++ code handling variable-length input from untrusted sources (repository data) without explicit bounds checking could be vulnerable to buffer overflows. Fix: Conduct thorough code review of string handling in directory and file processing. Use safe string libraries (e.g., std::string with bounds checking), implement size limits on path lengths, and validate all input from repository parsers before processing.
• Medium · External Script Execution Risk — scripts/gource-ps.pl, dev/bin/build_tar.pl, dev/bin/build_win64.pl, contrib/svn-gource.py. The repository contains Perl scripts (scripts/gource-ps.pl, dev/bin/build_tar.pl, dev/bin/build_win64.pl, contrib/svn-gource.py) that may execute system commands or process untrusted input without sufficient validation. Fix: Review all Perl and Python scripts for command injection vulnerabilities. Use Perl/Python security best practices: enable strict mode, use taint checking (-T flag), avoid backticks and system() with unsanitized input, and use array form of system() calls instead of shell strings.
• Low · Missing Security Headers in Build Configuration — configure.ac, Makefile.am, gource.pro. While not a direct code vulnerability, the build system (configure.ac, Makefile.am) should include security flags (ASLR, DEP/NX, stack canaries) during compilation for a visualization tool that processes untrusted data. Fix: Add compiler security flags to build configuration: -fstack-protector-strong, -D_FORTIFY_SOURCE=2, -fPIE, -pie for position-independent code. Enable warnings for dangerous functions and fix any identified issues.
• Low · Dependency on External Fonts and Resources — data/fonts/FreeSans.ttf. The application includes external font files (data/fonts/FreeSans.ttf) which could potentially be exploited if malformed or if the font parsing library has vulnerabilities. Fix: Keep font libraries updated, validate font file integrity, and consider using system fonts where possible. Regularly audit third-party font and resource dependencies for known vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.