GitStats

   _____ _ _   _____ _        _
  / ____(_) | / ____| |      | |
 | |  __ _| |_| (___ | |_ __ _| |_ ___
 | | |_ | | __|\___ \| __/ _` | __/ __|
 | |__| | | |_ ____) | || (_| | |_\__ \
  \_____|_|\__|_____/ \__\__,_|\__|___/

Powerful Git repository analyzer that provides comprehensive statistics, insights, and visualizations about your codebase.

Requirements

• Node.js 22.0.0 or higher
• Git installed and accessible in PATH

Installation

npm install -g @zubenelakrab/gitstats

Quick Start

# Full analysis in terminal
gitstats analyze /path/to/repo

# Generate HTML dashboard
gitstats analyze /path/to/repo -o dashboard.html

# Export as JSON
gitstats analyze /path/to/repo -f json

# Quick summary
gitstats summary /path/to/repo

# Generate all reports at once
gitstats report /path/to/repo -d ./reports

Commands

Global Options

All commands accept these filtering options:

| Option | Description | |--------|-------------| | -b, --branch <branch> | Analyze specific branch | | --since <date> | Only commits after this date (ISO format) | | --until <date> | Only commits before this date (ISO format) | | --author <author> | Filter by author (repeatable) | | --exclude <path> | Exclude paths by glob pattern (repeatable) | | --include <path> | Include only these paths (repeatable) | | --no-merges | Exclude merge commits | | --max-commits <n> | Maximum number of commits to analyze |

analyze - Full Repository Analysis

Run all analyzers and display a complete report.

gitstats analyze [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save report to file (format inferred from extension) | | -f, --format <format> | Output format: cli, json, html (default: cli) | | --theme <theme> | Theme for HTML: light or dark (default: dark) |

Examples:

# Terminal output (default)
gitstats analyze .

# Save HTML dashboard
gitstats analyze . -o report.html

# Explicit format
gitstats analyze . -f html -o report.html

# JSON to stdout
gitstats analyze . -f json

# JSON to file
gitstats analyze . -o data.json

# Filter by date range
gitstats analyze . --since 2025-01-01 --until 2025-12-31

# Filter by author
gitstats analyze . --author "John" --author "Jane"

# Specific branch, no merges
gitstats analyze . -b develop --no-merges

# Exclude directories
gitstats analyze . --exclude "node_modules/**" --exclude "dist/**"

# Include only source files
gitstats analyze . --include "src/**"

# Limit commits for faster analysis
gitstats analyze . --max-commits 500

# Combined: last 6 months, specific branch, HTML output
gitstats analyze . -b main --since 2025-09-01 --no-merges -o report.html

summary - Quick Overview

gitstats summary [path]

gitstats summary .
gitstats summary . --since 2025-01-01
gitstats summary . --author "John"

authors - Contributor Statistics

gitstats authors [path] [options]

| Option | Description | |--------|-------------| | -n, --top <n> | Show top N authors (default: 10) | | --sort <field> | Sort by: commits, additions, deletions (default: commits) |

gitstats authors . --top 20 --sort additions
gitstats authors . --since 2025-01-01 --sort deletions

hotspots - Code Hotspots & Risk Map

Files with high churn (potential technical debt), directory hotspots, and risk scoring.

gitstats hotspots [path] [options]

| Option | Description | |--------|-------------| | -n, --top <n> | Show top N hotspots (default: 15) |

gitstats hotspots . --top 30
gitstats hotspots . --exclude "*.test.*" --top 20

velocity - Development Velocity & Trends

Commits per day/week/month, trend analysis, consistency score, release rhythm, sprint cycle detection, codebase evolution.

gitstats velocity [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats velocity .
gitstats velocity . -o velocity.html
gitstats velocity . --since 2025-06-01 -b main

complexity - Code Complexity & Technical Debt

God files, growing files, refactoring candidates, debt scoring.

gitstats complexity [path] [options]

| Option | Description | |--------|-------------| | -n, --top <n> | Show top N items (default: 10) | | -o, --output <path> | Save HTML report to file |

gitstats complexity . --top 20
gitstats complexity . -o complexity.html --include "src/**"

commits - Commit Quality & Patterns

Commit type distribution, conventional commits %, WIP commits, large commits, author breakdown.

gitstats commits [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats commits .
gitstats commits . -o commits.html --no-merges

workpatterns - Work Patterns & Team Habits

Peak hours, night owl %, weekend commits, work-life balance score, timezone distribution.

gitstats workpatterns [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats workpatterns .
gitstats workpatterns . --author "John" -o patterns.html

collaboration - Team Collaboration

Collaboration pairs, shared files, lone wolves, knowledge silos.

gitstats collaboration [path] [options]

| Option | Description | |--------|-------------| | -n, --top <n> | Show top N items (default: 10) | | -o, --output <path> | Save HTML report to file |

gitstats collaboration . --top 20
gitstats collaboration . -o collaboration.html

coupling - File Coupling

Files that change together (temporal coupling), refactoring opportunities.

gitstats coupling [path] [options]

| Option | Description | |--------|-------------| | -n, --top <n> | Show top N items (default: 10) | | -o, --output <path> | Save HTML report to file |

gitstats coupling . --top 30
gitstats coupling . -o coupling.html --since 2025-01-01

health - Repository Health

Health score, zombie files, legacy code, abandoned directories, test metrics.

gitstats health [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats health .
gitstats health . -o health.html

busfactor - Bus Factor Analysis

Knowledge distribution, single points of failure, risky areas.

gitstats busfactor [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats busfactor .
gitstats busfactor . -o busfactor.html

branches - Branch Health

Stale branches, orphans, naming patterns, workflow detection, lifecycle metrics.

gitstats branches [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats branches .
gitstats branches . -o branches.html

burnout - Burnout Risk Detection

Team and individual burnout risk based on work patterns.

gitstats burnout [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats burnout .
gitstats burnout . -o burnout.html --since 2025-01-01

leaderboard - Gamified Stats

Contributor rankings, achievements, badges, fun stats.

gitstats leaderboard [path] [options]

| Option | Description | |--------|-------------| | -t, --top <n> | Show top N entries (default: 5) | | -o, --output <path> | Save HTML report to file |

gitstats leaderboard . --top 10
gitstats leaderboard . -o leaderboard.html

deadcode - Dead Code Detection

Potentially dead files, stale exports, unused dependencies.

gitstats deadcode [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats deadcode .
gitstats deadcode . -o deadcode.html --exclude "test/**"

dependencies - Dependency Analysis

Dependency health, circular dependencies, hub files, module clusters.

gitstats dependencies [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats dependencies .
gitstats dependencies . -o dependencies.html

duplicates - Code Duplication

Clone groups, duplication %, potential LOC savings, refactoring recommendations.

gitstats duplicates [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save HTML report to file |

gitstats duplicates .
gitstats duplicates . -o duplicates.html --include "src/**"

city - 3D Code City Visualization

Interactive 3D visualization where buildings = files, height = LOC, color = file type, districts = directories.

gitstats city [path] [options]

| Option | Description | |--------|-------------| | -o, --output <path> | Save 3D HTML visualization to file |

gitstats city .
gitstats city . -o city.html

diff - Compare Periods or Refs

Compare repository stats between two time periods or git refs.

gitstats diff [path] [options]

| Option | Description | |--------|-------------| | --period <days> | Compare last N days vs previous N days | | --base <ref> | Base ref or date (e.g. HEAD~10, 2024-01-01) | | --head <ref> | Head ref or date (default: HEAD) | | -o, --output <path> | Save diff report as HTML |

# Compare last 30 days vs previous 30 days
gitstats diff . --period 30

# Compare two git refs
gitstats diff . --base HEAD~50 --head HEAD

# Compare from a date
gitstats diff . --base 2025-01-01

# Save HTML report
gitstats diff . --base HEAD~20 --head HEAD -o diff.html

scorecard - CI/CD Health Checks

Run pass/fail checks against repository health thresholds. Exits with code 1 on failure (useful for CI pipelines).

gitstats scorecard [path] [options]

| Option | Description | |--------|-------------| | --bus-factor <n> | Minimum bus factor (default: 2) | | --health-score <n> | Minimum health score 0-100 (default: 50) | | --max-author-pct <n> | Max % commits by single author (default: 80) | | --min-authors <n> | Minimum contributors (default: 2) | | --strict | Treat warnings as failures | | -o, --output <path> | Save scorecard as HTML |

# Run scorecard with defaults
gitstats scorecard .

# Custom thresholds
gitstats scorecard . --bus-factor 3 --health-score 70

# Strict mode for CI (warnings = failures)
gitstats scorecard . --strict

# Save HTML report
gitstats scorecard . -o scorecard.html

report - Generate All Reports

Generates 16 HTML reports + an index page in one command.

gitstats report [path] [options]

| Option | Description | |--------|-------------| | -d, --dir <directory> | Output directory (default: ./gitstats-report) | | --theme <theme> | Theme for HTML: light or dark |

gitstats report . -d ./reports
gitstats report . -d ./reports --since 2025-01-01 --no-merges
gitstats report . -d ./reports --theme light

Generated files:

• index.html - Links to all reports
• analyze.html - Full analysis dashboard
• velocity.html - Development velocity
• busfactor.html - Bus factor analysis
• workpatterns.html - Work patterns
• complexity.html - Code complexity
• commits.html - Commit quality
• collaboration.html - Team collaboration
• coupling.html - File coupling
• health.html - Repository health
• branches.html - Branch analysis
• burnout.html - Burnout risk detection
• leaderboard.html - Contributor leaderboard
• deadcode.html - Dead code detection
• dependencies.html - Dependency analysis
• duplicates.html - Code duplication
• city.html - 3D Code City visualization

Configuration File

Create a .gitstats.yml in your repository root to set defaults:

# Paths to exclude from analysis
exclude:
  - "node_modules/**"
  - "dist/**"
  - "*.lock"

# Paths to include (overrides exclude for matching)
include:
  - "src/**"

# Default branch to analyze
branch: main

# Exclude merge commits
noMerges: true

# Maximum commits to analyze
maxCommits: 5000

# HTML theme: light or dark
theme: dark

# Enable/disable specific analyzers
analyzers:
  burnout: true
  leaderboard: true
  deadcode: false
  dependencies: true
  duplicates: false
  city: false
  velocity: true
  workpatterns: true
  commits: true
  collaboration: true
  coupling: true
  complexity: true
  health: true
  branches: true

# Scorecard thresholds
thresholds:
  busFactor: 2
  healthScore: 50

Config priority: defaults < .gitstats.yml < CLI flags. CLI flags always win.

Features

Core Analytics

• Commit Analytics - Total commits, lines added/deleted, activity over time
• Contributor Stats - Ranking by commits, additions, deletions, and file changes
• Code Hotspots - Identify files with high churn (potential technical debt)
• Bus Factor Analysis - Detect knowledge silos and single points of failure
• Timeline Analysis - Activity by day, week, month, year, hour of day

Advanced Analytics

• Velocity Analysis - Commits per day/week/month, trends, consistency score
• Codebase Evolution - LOC growth over time, largest expansions/refactors
• Complexity Analysis - God files, growing files, technical debt scoring
• Critical Hotspots - Files with high churn AND high changes (risk scoring)
• Work Patterns - Peak hours, night owl %, work-life balance score
• Commit Quality - Conventional commits %, WIP commits, large commits
• Collaboration - Pair programming detection, shared files, lone wolves
• Coupling Analysis - Files that change together (temporal coupling)
• Health Analysis - Zombie files, legacy code, test metrics
• Branch Analysis - Stale branches, orphans, workflow detection

Extended Analyzers

• Burnout Detection - Identify developer burnout risk based on work patterns
• Leaderboard - Gamified contributor stats with achievements and fun stats
• Dead Code Detection - Find potentially unused or abandoned code
• Dependency Analysis - File dependencies and circular dependency detection
• Code Duplication - Detect copy-paste code and refactoring opportunities
• Code City 3D - Interactive 3D visualization of your codebase

CI/CD Integration

• Scorecard - Pass/fail health checks with configurable thresholds and exit codes
• Diff - Compare stats between periods or git refs to track trends
• Config File - .gitstats.yml for reproducible team-wide settings

Output Formats

• CLI - Colored terminal output with charts and tables
• JSON - Machine-readable export for CI/CD integration
• HTML - Interactive dashboard with Chart.js visualizations (dark/light themes)

Understanding the Metrics

Churn Score

Measures how frequently a file is modified. High churn indicates potential technical debt or unstable code.

Formula: commits * log(lines_changed)

Technical Debt Score

0-100 score based on god files %, growing files %, refactoring candidates, and high churn files.

Bus Factor

The minimum number of contributors who would need to leave before significant knowledge is lost.

• 1 - Critical risk: only one person knows this code
• 2-3 - Medium risk: limited knowledge sharing
• 4+ - Healthy: knowledge is well distributed

Burnout Risk

Based on overtime work patterns, weekend commit frequency, late night coding, and sprint intensity.

Project Structure

gitstats/
├── src/
│   ├── cli/
│   │   └── index.ts              # CLI entry point (22 commands)
│   ├── config/
│   │   ├── index.ts              # Config barrel export
│   │   └── loader.ts             # .gitstats.yml discovery & parsing
│   ├── core/
│   │   └── analyzer.ts           # Main orchestrator
│   ├── parsers/
│   │   └── git-parser.ts         # Git log parsing
│   ├── analyzers/
│   │   ├── author-analyzer.ts    # Contributor stats
│   │   ├── timeline-analyzer.ts  # Time-based analysis
│   │   ├── hotspot-analyzer.ts   # Churn & risk analysis
│   │   ├── busfactor-analyzer.ts # Knowledge distribution
│   │   ├── velocity-analyzer.ts  # Speed & trends
│   │   ├── complexity-analyzer.ts # Debt & complexity
│   │   ├── commits-analyzer.ts   # Commit quality
│   │   ├── workpatterns-analyzer.ts # Work habits
│   │   ├── health-analyzer.ts    # Repo health
│   │   ├── collaboration-analyzer.ts # Team patterns
│   │   ├── coupling-analyzer.ts  # File coupling
│   │   ├── branches-analyzer.ts  # Branch health
│   │   ├── burnout-analyzer.ts   # Burnout detection
│   │   ├── leaderboard-analyzer.ts # Gamified stats
│   │   ├── deadcode-analyzer.ts  # Dead code detection
│   │   ├── dependency-analyzer.ts # Dependencies
│   │   ├── copypaste-analyzer.ts # Code duplication
│   │   ├── codecity-analyzer.ts  # 3D visualization
│   │   ├── diff-analyzer.ts     # Period/ref comparison
│   │   └── scorecard-analyzer.ts # CI health checks
│   ├── outputs/
│   │   ├── cli-renderer.ts       # Terminal output
│   │   ├── html-renderer.ts      # HTML dashboard
│   │   ├── json-renderer.ts      # JSON export
│   │   ├── analyzer-html-renderers.ts # Individual HTML reports
│   │   └── city3d-renderer.ts    # 3D Code City
│   ├── types/
│   │   └── index.ts              # TypeScript definitions
│   └── utils/
│       ├── exec.ts               # Git command execution
│       └── date.ts               # Date utilities
├── package.json
└── tsconfig.json

Changelog

0.1.5

New Features:

• diff command - Compare repository stats between two periods (--period 30) or git refs (--base HEAD~50 --head HEAD)
• scorecard command - CI/CD health checks with pass/fail/warn, configurable thresholds, --strict mode, exit code 1 on failure
• .gitstats.yml config file - Auto-discovered project config with exclude/include paths, analyzer toggles, scorecard thresholds, theme preference
• --theme on report command - Apply light/dark theme to all generated reports

Bug Fixes:

• Fix scorecard HTML showing PASSED when --strict causes CLI failure
• Fix disabledAnalyzers config only covering 6 of 14 optional analyzers
• Fix .gitstats.yml theme having no effect on HTML output
• Fix diff --period double-counting commits at period boundary
• Fix unrounded float in burnout Work-Life Balance display
• Fix All Contributors table numeric columns not right-aligned
• Fix incorrect sprint cycle author counting that produced wrong metrics
• Fix file status detection now using file.status instead of inferring from additions/deletions
• Fix date parsing with validation to prevent Invalid Date propagation
• Fix version mismatch in CLI help output
• Remove self-dependency in package.json that caused installation issues

Improvements:

• New -o, --output and -f, --format options on analyze command (replaces old -f, --file)
• Format auto-detection from file extension (.html -> html, .json -> json)
• All commands now support filtering options (--branch, --since, --until, --author, --exclude, --include, --no-merges, --max-commits)
• Renamed -f, --file to -o, --output across all subcommands for consistency
• Replaced 42 non-null assertions with safe get-then-init pattern across 15 analyzer files
• Removed unimplemented markdown and csv from OutputFormat type
• Switched dev runner from --experimental-strip-types to tsx for Node 24 compatibility

0.1.4

• Bump version

0.1.3

• Add 6 new analyzers: burnout, leaderboard, deadcode, dependencies, duplicates, code city
• Add individual HTML renderers for all analyzers
• Add report command to generate all reports at once

0.1.2

• Update README with npm installation instructions

License

MIT