git-stats-cli

Production-grade CLI to analyze Git repositories locally using go-git and go-enry (GitHub Linguist rules).

No git binary required.

Features

• Complete commit scan — analyzes every commit object available locally (all branches/tags present in the object database)
• Linguist-compatible languages — byte share, file counts, and percentages at HEAD
• Authors — unique contributor count + configurable top-N ranking
• Activity windows — 30 / 90 / 365 days
• Monthly trends — configurable number of recent months
• Code churn — lines added/deleted and files changed (disable with --no-churn)
• Repository metadata — default branch, branch/tag counts, bare & shallow detection
• Reports — JSON, Markdown, HTML
• Cross-platform releases — GoReleaser builds for Linux, macOS, Windows (amd64 + arm64)

Installation

Go install

go install github.com/loSpaccaBit/git-stats-cli/cmd/git-stats@latest

Docker

docker build -t git-stats-cli .
docker run --rm -v "$(pwd):/repo" git-stats-cli analyze /repo

GitHub Releases

Download binaries from Releases.

Usage

# Terminal report (fast — churn off by default)
git-stats analyze .
git-stats analyze /path/to/repo

# Enable churn stats on large repos (slower, uses parallel workers)
git-stats --churn analyze /path/to/repo
git-stats --churn --workers 8 analyze /path/to/repo

# Show timing
git-stats -v analyze /path/to/repo

# Disable colors
git-stats --no-color analyze .

# Show top 20 authors, last 6 months
git-stats --top 20 --months 6 analyze .

# Export reports
git-stats report -f json -o report.json .
git-stats report -f md -o report.md .
git-stats report -f html -o report.html .

# Version
git-stats --version

Output

Terminal (analyze)

• Repository path, commits, authors
• Branch/tag metadata, shallow/bare flags
• Activity (30/90/365 days)
• Code churn (lines added/deleted, files changed)
• Top authors table
• Languages at HEAD with bytes and percentage (Linguist)
• Monthly commit trend
• Warnings (e.g. shallow clone, empty repository)

Reports (report)

Same data in machine-readable JSON or human-readable Markdown/HTML.

Tech Stack

Layer	Technology
Language	Go 1.22+
CLI	Cobra
Git parsing	go-git
Language detection	go-enry (Linguist)
Terminal output	fatih/color, tablewriter
Testing	testing + testify
CI/CD	GitHub Actions + GoReleaser

Project Structure

git-stats-cli/
├── cmd/git-stats/          # CLI entrypoint
├── internal/
│   ├── analyzer/           # Analysis engine
│   ├── formatter/          # Terminal + export renderers
│   ├── git/                # go-git wrapper + language detection
│   ├── report/             # Report orchestration
│   └── version/            # Build version injection
├── pkg/stats/              # Shared data models
└── .github/workflows/      # CI and release pipelines

Development

git clone https://github.com/loSpaccaBit/git-stats-cli.git
cd git-stats-cli
go test ./...
go build -o git-stats ./cmd/git-stats

Releasing

git tag v0.1.0
git push origin v0.1.0

GoReleaser publishes multi-platform binaries and attaches checksums automatically.

Performance

Mode	When to use
Default (no --churn)	Day-to-day use, large repos, reports json/md/html
--churn	When you need lines added/deleted; parallelized via --workers
-v / --verbose	Prints analysis duration to stderr

Benchmark on a local repo:

GIT_STATS_BENCH_REPO=/path/to/repo go test ./internal/analyzer -bench=. -benchmem

Limitations

• Analysis is local only — only objects present in the repository are counted.
• Shallow clones analyze available history; a warning is shown when .git/shallow is detected.
• Language stats reflect the HEAD tree, not historical composition.

License

MIT — see LICENSE.