22
33[ ![ CI] ( https://github.com/loSpaccaBit/git-stats-cli/actions/workflows/ci.yml/badge.svg )] ( https://github.com/loSpaccaBit/git-stats-cli/actions/workflows/ci.yml )
44[ ![ License: MIT] ( https://img.shields.io/badge/License-MIT-yellow.svg )] ( LICENSE )
5- [ ![ Go Report Card] ( https://goreportcard.com/badge/github.com/loSpaccaBit/git-stats-cli )] ( https://goreportcard.com/report/github.com/loSpaccaBit/git-stats-cli )
65
7- A command-line tool to analyze Git repositories and generate insightful reports — without requiring the ` git ` binary installed .
6+ Production-grade CLI to analyze Git repositories locally using ** go-git ** and ** go-enry ** (GitHub Linguist rules) .
87
9- Built with ** Go ** , ** Cobra ** , and ** go-git ** .
8+ No ` git ` binary required .
109
1110## Features
1211
13- - Analyze local repositories with ` git-stats analyze `
14- - Terminal output with colored tables (disable with ` --no-color ` )
15- - Export reports as JSON, Markdown, or HTML
16- - Cross-platform binaries via GoReleaser
17- - Docker support
12+ - ** Complete commit scan** — analyzes every commit object available locally (all branches/tags present in the object database)
13+ - ** Linguist-compatible languages** — byte share, file counts, and percentages at ` HEAD `
14+ - ** Authors** — unique contributor count + configurable top-N ranking
15+ - ** Activity windows** — 30 / 90 / 365 days
16+ - ** Monthly trends** — configurable number of recent months
17+ - ** Code churn** — lines added/deleted and files changed (disable with ` --no-churn ` )
18+ - ** Repository metadata** — default branch, branch/tag counts, bare & shallow detection
19+ - ** Reports** — JSON, Markdown, HTML
20+ - ** Cross-platform releases** — GoReleaser builds for Linux, macOS, Windows (amd64 + arm64)
1821
1922## Installation
2023
@@ -33,32 +36,53 @@ docker run --rm -v "$(pwd):/repo" git-stats-cli analyze /repo
3336
3437### GitHub Releases
3538
36- Download the latest binary for your OS from [ Releases] ( https://github.com/loSpaccaBit/git-stats-cli/releases ) .
39+ Download binaries from [ Releases] ( https://github.com/loSpaccaBit/git-stats-cli/releases ) .
3740
3841## Usage
3942
40- ### Analyze a repository
41-
4243``` bash
44+ # Terminal report (fast — churn off by default)
4345git-stats analyze .
4446git-stats analyze /path/to/repo
47+
48+ # Enable churn stats on large repos (slower, uses parallel workers)
49+ git-stats --churn analyze /path/to/repo
50+ git-stats --churn --workers 8 analyze /path/to/repo
51+
52+ # Show timing
53+ git-stats -v analyze /path/to/repo
54+
55+ # Disable colors
4556git-stats --no-color analyze .
57+
58+ # Show top 20 authors, last 6 months
59+ git-stats --top 20 --months 6 analyze .
60+
61+ # Export reports
62+ git-stats report -f json -o report.json .
63+ git-stats report -f md -o report.md .
64+ git-stats report -f html -o report.html .
65+
66+ # Version
67+ git-stats --version
4668```
4769
48- Output includes:
70+ ## Output
4971
50- - Total commits
51- - Top authors by commit count
52- - Languages detected from file extensions
53- - Activity in the last 30 and 90 days
72+ ### Terminal (` analyze ` )
5473
55- ### Generate a report
74+ - Repository path, commits, authors
75+ - Branch/tag metadata, shallow/bare flags
76+ - Activity (30/90/365 days)
77+ - Code churn (lines added/deleted, files changed)
78+ - Top authors table
79+ - Languages at HEAD with bytes and percentage (Linguist)
80+ - Monthly commit trend
81+ - Warnings (e.g. shallow clone, empty repository)
5682
57- ``` bash
58- git-stats report --format=json --output=report.json .
59- git-stats report --format=md --output=report.md .
60- git-stats report --format=html --output=report.html .
61- ```
83+ ### Reports (` report ` )
84+
85+ Same data in machine-readable JSON or human-readable Markdown/HTML.
6286
6387## Tech Stack
6488
@@ -67,8 +91,8 @@ git-stats report --format=html --output=report.html .
6791| Language | Go 1.22+ |
6892| CLI | Cobra |
6993| Git parsing | go-git |
94+ | Language detection | go-enry (Linguist) |
7095| Terminal output | fatih/color, tablewriter |
71- | Reports | encoding/json, text/html templates |
7296| Testing | testing + testify |
7397| CI/CD | GitHub Actions + GoReleaser |
7498
@@ -78,51 +102,53 @@ git-stats report --format=html --output=report.html .
78102git-stats-cli/
79103├── cmd/git-stats/ # CLI entrypoint
80104├── internal/
81- │ ├── analyzer/ # Repository analysis logic
82- │ ├── formatter/ # JSON, Markdown, HTML, terminal output
83- │ ├── git/ # go-git wrapper
84- │ └── report/ # Report generation
105+ │ ├── analyzer/ # Analysis engine
106+ │ ├── formatter/ # Terminal + export renderers
107+ │ ├── git/ # go-git wrapper + language detection
108+ │ ├── report/ # Report orchestration
109+ │ └── version/ # Build version injection
85110├── pkg/stats/ # Shared data models
86111└── .github/workflows/ # CI and release pipelines
87112```
88113
89114## Development
90115
91- ### Prerequisites
92-
93- - Go 1.22+
94- - Git (for development only; runtime uses go-git)
95-
96- ### Setup
97-
98116``` bash
99117git clone https://github.com/loSpaccaBit/git-stats-cli.git
100118cd git-stats-cli
101- go mod download
119+ go test ./...
120+ go build -o git-stats ./cmd/git-stats
102121```
103122
104- ### Run tests
123+ ## Releasing
105124
106125``` bash
107- go test ./...
126+ git tag v0.1.0
127+ git push origin v0.1.0
108128```
109129
110- ### Build locally
130+ GoReleaser publishes multi-platform binaries and attaches checksums automatically.
111131
112- ``` bash
113- go build -o git-stats ./cmd/git-stats
114- ./git-stats analyze .
115- ```
132+ ## Performance
116133
117- ## Releasing
134+ | Mode | When to use |
135+ | ------| -------------|
136+ | Default (no ` --churn ` ) | Day-to-day use, large repos, reports json/md/html |
137+ | ` --churn ` | When you need lines added/deleted; parallelized via ` --workers ` |
138+ | ` -v ` / ` --verbose ` | Prints analysis duration to stderr |
118139
119- Tag a version to trigger GoReleaser :
140+ Benchmark on a local repo :
120141
121142``` bash
122- git tag v0.1.0
123- git push origin v0.1.0
143+ GIT_STATS_BENCH_REPO=/path/to/repo go test ./internal/analyzer -bench=. -benchmem
124144```
125145
146+ ## Limitations
147+
148+ - Analysis is ** local only** — only objects present in the repository are counted.
149+ - ** Shallow clones** analyze available history; a warning is shown when ` .git/shallow ` is detected.
150+ - Language stats reflect the ** HEAD tree** , not historical composition.
151+
126152## License
127153
128154MIT — see [ LICENSE] ( LICENSE ) .
0 commit comments