📈 gitstats

Deep git repo analytics in your terminal — contributors, hotspots, code churn, effort estimation & beautiful ASCII reports.

Know your codebase like never before. One command, zero config.

✨ Features

• 🔍 Full repo analysis — commits, contributors, files, churn, frequency heatmap
• 🔥 Hotspot detection — find your most-changed files
• 📊 ASCII bar charts — beautiful Rich-powered terminal output
• ⏱️ Effort estimation — approximate developer hours & sessions
• 🔎 Blame viewer — who owns each line, with ownership summary
• 📋 One-line summary — "2,341 commits by 12 devs across 890 files over 3.2 years"
• ⚖️ Repo comparison — compare two repos side by side
• 📦 JSON output — pipe into jq or your favorite tool
• 🚀 Zero config — just point it at a git repo

🚀 Quick Start

# Install
pip install -e .

# Analyze any repo
gitstats analyze /path/to/repo

# One-line summary
gitstats summary /path/to/repo

# Who wrote this file?
gitstats blame src/main.py

# Estimate developer effort
gitstats effort /path/to/repo

# Compare two repos
gitstats compare /path/to/repo1 /path/to/repo2

# JSON output for scripting
gitstats analyze /path/to/repo --format json

📖 Commands

gitstats analyze <path>

Full repo analysis with:

• Total commits, contributors, files
• Top contributors (with bar charts)
• Most-changed files (hotspots)
• Code churn ratio (added vs deleted)
• Commit frequency heatmap by hour & day
• Language distribution
• Repo age

gitstats blame <file>

Rich blame output showing who owns each line, with an ownership summary at the bottom.

gitstats effort <path>

Estimates developer effort based on commit patterns:

• Number of coding sessions (3h gap heuristic)
• Estimated total hours
• Per-developer breakdown

gitstats summary <path>

One-line repo summary:

📋 342 commits by 5 devs across 127 files over 1.2 years

gitstats compare <repo1> <repo2>

Side-by-side comparison of two repos — commits, contributors, files, churn, languages, age.

🔧 Use as a Library

from gitstats.git_helpers import get_summary, get_contributors, get_churn

summary = get_summary("/path/to/repo")
print(summary)  # "342 commits by 5 devs..."

contributors = get_contributors("/path/to/repo")
for c in contributors:
    print(f"{c['name']}: {c['commits']} commits")

churn = get_churn("/path/to/repo")
print(f"Churn ratio: {churn['ratio']}")

🆚 Comparison

Feature	gitstats	git-quick-stats	gitstats (Go)
Language	Python	Bash	Go
Rich terminal UI	✅	❌	❌
JSON output	✅	❌	❌
Effort estimation	✅	❌	❌
Repo comparison	✅	❌	❌
Zero config	✅	✅	✅
Blame viewer	✅	❌	❌
Install size	Small	Tiny	Medium

📋 Requirements

• Python 3.8+
• Git (in PATH)
• Rich (auto-installed)
• Click (auto-installed)

🗺️ Roadmap

• SVG/PNG chart export
• Git merge request analysis
• Team velocity trends over time
• Web dashboard mode
• GitHub/GitLab API integration
• Config file support (.gitstatsrc)
• CI/CD pipeline health metrics

📄 License

MIT — see LICENSE

---

Built with ❤️ by zehedisodef1-oss