📊 repo-stats

Advanced Repository Analysis CLI — understand any codebase in seconds, directly from your terminal.

Supports local directories and remote Git repositories (GitHub, GitLab, Bitbucket).
No dependencies beyond Python 3.10+ and git.

---

Installation

git clone https://github.com/pfurpass/repo-stats
cd repo-stats
bash install.sh

Then add ~/.local/bin to your PATH (the installer will remind you):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

---

Usage

repo-stats .                                         # current directory
repo-stats /path/to/project                          # local path
repo-stats https://github.com/user/repo              # remote URL
repo-stats user/repo                                 # GitHub shorthand
repo-stats user/repo --full-clone                    # full git history

Remote repositories are automatically cloned into a temporary directory and cleaned up afterwards.
By default a shallow clone (--depth 1) is used for speed. Use --full-clone to get accurate commit counts.

---

Example Output

  ╔═══════════════════════════════════════╗
  ║   repo-stats  ·  pfurpass/DataHeater  ║
  ╚═══════════════════════════════════════╝
  Path: /tmp/repo-stats-q3_qma7w
  Branch: master

  File Statistics
  ─────────────────
  Files:             21
  Total Size:        152.3 KB
  Lines of Code:     3,591
    Code:            2,988
    Comments:        164
    Blank:           439

  Languages
  ───────────
  C#                   █████████████░░░░░ 73.8%  14 files, 2,649 lines
  Other                ████░░░░░░░░░░░░░░ 22.4%   6 files,   804 lines
  Markdown             █░░░░░░░░░░░░░░░░░  3.8%   1 files,   138 lines

  Git Statistics
  ────────────────
  Commits:             33
  Contributors:        2
  First commit:        2026-03-04
  Last commit:         2026-03-08
  Repository age:      4 days

  Contributors
  ──────────────
  SchwitzerSkills      ████████████████░░  87.1%  27 commits
  Phillip F            ██░░░░░░░░░░░░░░░░  12.9%   4 commits

---

CLI Options

Flag	Short	Description
--files	-f	File statistics & largest files
--languages	-l	Language distribution
--git	-g	Git history & activity
--contributors	-c	Contributor breakdown with ownership %
--directories	-d	Top directories by lines of code
--todos	-t	TODO / FIXME / BUG / HACK markers
--dependencies / --deps		Detected package dependencies
--health		Code quality indicators
--json		Output as JSON
--markdown / --md		Output as Markdown table
--full-clone		Full git clone (accurate commit history)
--no-color		Disable ANSI color output
--top N		Show top N items (default: 10)

When called with no flags, all sections are shown.

---

Selective Sections

repo-stats . --languages --contributors
repo-stats user/repo --git --todos
repo-stats . --json | jq '.loc'
repo-stats . --markdown > report.md

---

What It Detects

Languages (60+)

Python, JavaScript, TypeScript, C#, Java, Go, Rust, Ruby, PHP, Swift, Kotlin, Dart, Elixir, Erlang, Haskell, Scala, Lua, Perl, Shell, PowerShell, HTML, CSS, SCSS, SQL, YAML, TOML, Dockerfile, Makefile, Vue, Svelte, F#, Groovy, Terraform, and more.

Dependency Files

File	Ecosystem
package.json	Node.js (npm)
requirements.txt / Pipfile / pyproject.toml	Python
Cargo.toml	Rust
go.mod	Go
*.csproj	NuGet (.NET)
pom.xml / build.gradle	Java (Maven / Gradle)
composer.json	PHP
Gemfile	Ruby
pubspec.yaml	Dart / Flutter
Package.swift	Swift
mix.exs	Elixir

Developer Markers

TODO · FIXME · BUG · HACK · NOTE · XXX · OPTIMIZE · REVIEW · DEPRECATED

---

Output Formats

Human-readable (default)

Colored terminal output with progress bars and aligned columns.

JSON

repo-stats . --json

{
  "repo": "DataHeater",
  "loc": { "total": 3591, "code": 2988, "comments": 164, "blank": 439 },
  "languages": { "C#": { "files": 14, "lines": 2649, "pct": 73.8 } },
  "git": { "commits": 33, "contributors": [...] },
  "todos": { "NOTE": 10 },
  "dependencies": { "NuGet (.NET)": 6 }
}

Markdown

repo-stats . --markdown > REPORT.md

Produces a full Markdown report with tables, ready for GitHub wikis or documentation.

---

Performance

• Parallel scanning via ThreadPoolExecutor (up to 16 workers)
• Shallow clones (--depth 1) by default — fast even on large repositories
• Auto-ignored directories: node_modules, .git, build, dist, bin, obj, __pycache__, venv, .next, target, vendor, and more
• Binary files are detected and skipped automatically

---

Shallow vs. Full Clone

	Shallow (default)	Full (--full-clone)
Speed	⚡ Fast	🐢 Slower
File stats	✅ Accurate	✅ Accurate
Commit count	⚠️ Shows 1	✅ Accurate
Contributor history	⚠️ Partial	✅ Complete
Recommended for	Quick code analysis	Git history analysis

---

Requirements

• Python 3.10+
• git (for remote cloning and history analysis)

---

License

Apache