feat: add JSON output option

[mloncarevich]

Summary

• Add --json / -j flag to output statistics as JSON
• Useful for scripting, piping to jq, or integrating with other tools

Usage

# Pretty terminal output (default)
gitstats stats

# JSON output
gitstats stats --json

# Pipe to jq
gitstats stats --json | jq '.authors[0]'

Example output

{
  "repository": ".",
  "total_commits": 42,
  "total_authors": 3,
  "first_commit": "2024-01-15",
  "last_commit": "2026-02-06",
  "authors": [...],
  "weekly_activity": [...],
  "hourly_activity": [...]
}

Made with Cursor

---

Note

Low Risk
Primarily adds an alternate output format and small CLI branching; core parsing/stat computation is unchanged, so behavioral risk is limited to output/compat expectations.

Overview
Adds a --json/-j flag to gitstats stats to emit machine-readable JSON instead of the rich/pretty terminal output.

The JSON payload includes repository path, commit/author totals, first/last commit dates, per-author stats, and computed weekly/hourly activity; error cases now also return JSON when the flag is used. Documentation is updated to list the feature and show usage examples.

^{Written by Cursor Bugbot for commit 18470cd. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

This is the final PR Bugbot will review for you during this billing cycle

Your free Bugbot reviews will reset on March 3

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[cursor]

Rich console.print corrupts machine-readable JSON output

High Severity

Using Rich's console.print for JSON output intended for machine consumption (jq, scripting) is incorrect. Rich's Console.print applies syntax highlighting (ANSI escape codes in terminal), soft-wraps text to the terminal/default width (breaking long JSON lines), and interprets Rich markup (square brackets in JSON values could be misinterpreted). All three behaviors can produce invalid JSON. Python's built-in print() is the appropriate choice here.

Additional Locations (1)

• gitstats/cli.py#L57-L58