git-metrics

Self-contained git contributor statistics: CLI + interactive HTML dashboard.
Configuration and generated reports live inside this repository — the analyzed repo is never modified.

Requirements

• Python 3.11+
• Git on PATH
• Full local clone of the target repo (git fetch --unshallow if shallow)

Layout

git-metrics/
  generate.py
  git-metrics.config.json      # optional (copy from example)
  git-metrics.config.example.json
  reports/                     # generated (gitignored)
    git-metrics.html
    git-metrics.json

Usage

Submodule in a parent repo

git submodule add <url> tools/git-metrics
cd tools/git-metrics
cp git-metrics.config.example.json git-metrics.config.json   # optional
npm run generate

When run from a submodule, the parent repository is analyzed automatically.
Outputs are written under tools/git-metrics/reports/ — no changes to the parent .gitignore.

Standalone

python generate.py --repo /path/to/target/repo --json

Options

Flag	Description
--repo	Target repository (default: git superproject or parent of tool dir)
--config	Config path (default: ./git-metrics.config.json)
--output	HTML path relative to tool dir (default: reports/git-metrics.html)
--json	Also write JSON (default: reports/git-metrics.json)
--skip-blame	Fast run without blame data
GIT_METRICS_TARGET_REPO	Env override for target repo path

Configuration

Edit git-metrics.config.json in this directory:

• excluded_path_prefixes — extra prefixes excluded from the code scope
• path_scopes — optional prefix scopes (e.g. frontend/, backend/)

Built-in scopes: all, code.

Credentials

• Clone this repo: normal git remote auth.
• Analysis: reads the target repo’s local .git only (no network unless history is missing).

CI

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

- run: python tools/git-metrics/generate.py --repo "${{ github.workspace }}" --json
  working-directory: tools/git-metrics