reveille 0.6.0

A CLI tool that generates self-contained HTML performance reports from local Git repositories.

Reveille

A CLI tool that generates performance reports from local Git repositories — as self-contained HTML, structured JSON, and CSV.

Reveille reads your repository's Git history and produces a single portable .html file containing interactive visualisations of contributor activity, commit trends, code volume, and repository health — with no server, no external API calls, and no configuration beyond the command itself. Open the output in any browser, share it over email, or drop it into a Confluence page without modification.

---

Contents

• Overview
• Installation
• Quickstart
• CLI Reference
• Output Description
• Contributor Ranking System
• Configuration
• Documentation
• Development Setup
• Running Tests
• Contributing
• Changelog
• Licence

---

Overview

Reveille is designed for developers, engineering managers, and technical leads who need a production-grade, shareable retrospective from any Git repository — without configuring infrastructure or connecting to external services.

What it produces:

• Contribution heatmap with a GitHub-style year-navigable grid showing per-day commit activity. Year tabs allow switching between calendar years; a contributor dropdown surfaces per-contributor views alongside the aggregated default.
• Aggregate weekly commit timeline and per-contributor commit frequency chart, enabling direct comparison of burst contributors versus contributors with sustained low-volume engagement across the analysis window
• Per-contributor breakdowns covering commits, lines added and removed, and active day counts
• A structured ranking table assigning each contributor a tier designation based on weighted activity metrics
• Repository health indicators including bus factor, longest inactive streak, and consistency scores
• Machine-readable output in JSON (ranked contributor statistics and repository metadata) and CSV (contributor table with BOM encoding for Excel compatibility) via --format json, --format csv

Design constraints that are non-negotiable:

• The output is always a single .html file. No directories, no asset folders, no dependencies.
• The file must open in any modern browser with no internet connection. All JavaScript, CSS, and chart data are embedded inline.
• No external CDN calls. No iframes. No cookies. No tracking.
• The output aesthetic is formal and stakeholder-ready. No emojis. No casual language. Typography is clean and readable.

Security and observability: The project is continuously scanned by GitHub CodeQL (static analysis on every pull request) and OpenSSF Scorecard (automated security health scoring on every push to main). Pipeline progress is reported via structured events carrying per-stage elapsed time, enabling CI log analysis of generation bottlenecks in large repositories.

---

Installation

Reveille requires Python 3.11 or later.

pip

pip install reveille

pipx (recommended for CLI tools)

pipx install reveille

uv

Install permanently as a tool:

uv tool install reveille

Run without a permanent install:

uvx reveille generate --repo /path/to/repository

Poetry (within a Poetry-managed project)

poetry add reveille

Verify the installation:

reveille --version

---

Quickstart

Navigate to any Git repository on your machine and run:

cd /path/to/your/repository
reveille generate

Reveille reads the local Git history and writes a report to the current directory. The output file is named reveille-report.html by default. Open it in any browser.

Scaffold a configuration file before your first run:

reveille init

This writes an annotated reveille.toml to the current directory with every available configuration key present and commented out. Edit only the keys you need. On all subsequent invocations, reveille generate will detect and load reveille.toml automatically — no --config flag required.

Generate a report for a specific date range:

reveille generate --since 2024-01-01 --until 2024-12-31

Write the output to a specific path:

reveille generate --output /tmp/q4-report.html

Specify the repository path explicitly:

reveille generate --repo /path/to/repository

---

CLI Reference

reveille generate

Generates the HTML performance report for the target repository.

Flag	Short	Type	Default	Description
--repo	-r	PATH	. (current directory)	Path to the Git repository root. Must contain a .git directory.
--output	-o	PATH	./reveille-report.html	Path for the generated HTML file. Parent directories must exist.
--since		DATE	Repository creation date	Include only commits on or after this date. Accepts YYYY-MM-DD.
--until		DATE	Today	Include only commits on or before this date. Accepts YYYY-MM-DD.
--branch	-b	TEXT	Default branch	Analyse commits reachable from this branch only.
--exclude-author		TEXT	None	Exclude a contributor by name or email. Repeatable.
--min-commits		INT	1	Exclude contributors with fewer than this many commits in the analysis window.
--title		TEXT	Repository name	Override the report title displayed in the HTML output.
--no-ranking		Flag	Off	Omit the contributor ranking table from the output.
--format		TEXT	html	Output format. Accepted values: html, json, csv. json and csv write files at the same path stem as --output.
--config	-c	PATH	None	Path to a TOML configuration file. If omitted, reveille.toml in the current working directory is loaded automatically when present. Use this flag for non-standard file names or paths outside the repository root. CLI flags always take precedence over configuration file values.

reveille init

Scaffolds a fully annotated reveille.toml configuration file in the current directory. Every available key is present, commented out, and documented inline. Run this once before your first reveille generate invocation to produce a starting point you can edit rather than constructing the file from scratch.

Flag	Short	Type	Default	Description
--output	-o	PATH	./reveille.toml	Destination path for the generated configuration file.
--force		Flag	Off	Overwrite an existing file at the target path without prompting.
--mailmap		Flag	Off	Generate an annotated .mailmap template at the repository root alongside reveille.toml. Documents two-field, three-field, and four-field format variants with real-world examples. An existing .mailmap is silently skipped.

reveille version

Prints the installed version string and exits.

reveille validate

Validates that the target path is a readable Git repository and that the analysis window contains at least one commit. Exits with a non-zero status code if validation fails. Useful for CI integration.

reveille validate --repo /path/to/repository

reveille help

Displays the top-level help text listing all available commands and global options. Equivalent to reveille --help and reveille -h. The short flag -h is available on every subcommand — for example, reveille generate -h displays the full flag reference for the generate command.

reveille help

---

Output Description

The generated HTML file is structured as a formal report with the following sections.

Repository Summary — Name, remote URL if present, default branch, total commits in the analysis window, unique contributors, date range, and report generation timestamp.

Activity Heatmap — A GitHub-style year-navigable grid showing commit frequency by calendar day. Rows represent days of the week (Monday–Sunday); columns represent calendar weeks. Year tabs derived from the analysis window allow switching between calendar years without regenerating the report. A contributor dropdown provides per-contributor views alongside the aggregated default; single-contributor repositories hide the dropdown automatically.

Commit Timeline — A rolling area chart showing commit volume per calendar week over the analysis window. Highlights periods of high and low activity.

Per-Contributor Commit Frequency — A multi-trace line chart showing weekly commit frequency for each contributor individually across the analysis window. Each contributor is represented as a separate trace, enabling direct comparison of burst contributors versus those with sustained low-volume engagement — a distinction the aggregate timeline cannot convey.

Contributor Summary Table — A ranked table listing each contributor with their commit count, lines added, lines removed, net line delta, active days, most recent commit date, and assigned tier designation.

Contribution Breakdown Charts — Horizontal bar charts of commits and lines changed per contributor, and two donut charts showing each contributor's proportional share of total commits and total lines changed.

Repository Health Indicators — Bus factor estimate (minimum number of contributors accounting for 50% of commits) and longest inactive streak within the analysis window.

JSON export — When --format json is used, a structured JSON file is written at the same path stem as the HTML output. The payload contains repository metadata, ranked contributor statistics with all scoring fields, and derived health metrics. Suitable for dashboards, data warehouses, and CI integrations without parsing HTML.

CSV export — When --format csv is used, the ranked contributor table is written as a UTF-8 CSV file with BOM encoding. BOM ensures correct column rendering in Microsoft Excel on Windows without requiring a manual import wizard. Columns: rank, name, email, designation, tier, commits, lines added, lines deleted, net lines, active days, last commit date, composite score, percentile.

All charts are rendered with Plotly and are fully interactive — hover states, zoom, pan, and legend toggling are available without any external dependencies.

---

Contributor Ranking System

Reveille assigns each contributor a tier designation based on a weighted composite of four metrics.

Metric	Default Weight
Commit volume	30%
Lines contributed (additions + deletions)	25%
Activity consistency (active days / total days)	25%
Recency (decay-weighted recent activity)	20%

Weights are configurable. See Configuration.

The composite score maps to the following tier designations, applied relative to the contributor population in the analysis window.

Tier	Designation	Composite Score Percentile
I	Private	0 – 20th
II	Corporal	21st – 40th
III	Sergeant	41st – 60th
IV	Lieutenant	61st – 75th
V	Captain	76th – 88th
VI	Major	89th – 95th
VII	Commander	96th – 100th

Tier boundaries and weights are documented defaults and are fully reproducible from the source. Changing the weights changes the scores but not the tier logic. Tiers are always relative to the contributor population within the analysis window, not absolute thresholds.

---

Configuration

Reveille accepts a TOML configuration file for parameters that are cumbersome to pass on the command line on every invocation.

Canonical workflow. Run reveille init from your repository root to generate an annotated reveille.toml. Edit only the keys relevant to your analysis. From that point, reveille generate detects and loads reveille.toml automatically on every invocation — no flag required.

Non-standard paths. If the configuration file is named differently or stored outside the repository root, pass its path explicitly with --config. This is also the appropriate path for automation scripts that maintain multiple named configuration files for different analysis windows.

A fully commented reveille.toml is equivalent to no configuration file: all built-in defaults apply. A partially configured file applies only the keys present; absent keys fall back to defaults. A malformed file causes reveille generate to exit with a non-zero status, a parse error detail, and a remediation hint.

[report]
title = "Engineering Performance Report — Q4 2024"
output = "./reports/q4-2024.html"
branch = "main"
since = "2024-10-01"
until = "2024-12-31"
format = "html"

[filters]
min_commits = 2
exclude_authors = [
    "dependabot[bot]",
    "github-actions[bot]",
]

[ranking]
enabled = true
weights = { commits = 0.30, lines = 0.25, consistency = 0.25, recency = 0.20 }

CLI flags always take precedence over configuration file values. The configuration file is entirely optional — all values have defaults.

---

Documentation

A full operational reference is available at docs/USER_GUIDE.md. It covers every CLI flag and its interaction effects, every TOML key with annotated examples, the ranking algorithm in plain language, how to interpret each section of the generated report, and practical patterns for common use cases.

---

Development Setup

Prerequisites: Python 3.11 or later, git.

git clone [e-mail]:varaprasadchilakanti/reveille.git
cd reveille
poetry install

Verify the environment:

poetry run reveille --version
poetry run mypy src/
poetry run ruff check src/

---

Running Tests

pytest

With coverage report:

pytest --cov=reveille --cov-report=term-missing

Type checking only:

mypy src/

Linting only:

ruff check src/

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request. It covers the development environment setup, architecture overview, pull request contract, code style requirements, and commit message conventions.

---

Changelog

See CHANGELOG.md for the full release history. Reveille follows Keep a Changelog format and Semantic Versioning 2.0.

---

Licence

Reveille is released under the MIT Licence.