GitStats

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

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

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

Output Formats

• CLI - Colored terminal output with charts
• JSON - Machine-readable export
• HTML - Interactive dashboard with Chart.js visualizations

Requirements

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

Installation

npm install -g @zubenelakrab/gitstats

Usage

gitstats <command> [path] [options]

Commands

summary

Quick overview of a repository.

gitstats summary /path/to/repo

analyze

Full analysis with all metrics.

gitstats analyze /path/to/repo

# Export to HTML dashboard
gitstats analyze /path/to/repo -o html -f report.html

# Export to JSON
gitstats analyze /path/to/repo -o json -f report.json

Options:

• -o, --output <format> - Output format: cli, json, html (default: cli)
• -f, --file <path> - Save output to file
• -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 (can be used multiple times)
• --exclude <path> - Exclude paths (glob pattern)
• --include <path> - Include only these paths
• --no-merges - Exclude merge commits
• --max-commits <n> - Maximum number of commits to analyze
• --theme <theme> - Theme for HTML output: light, dark

authors

List contributors with their statistics.

gitstats authors /path/to/repo --top 10

hotspots

Show files with highest churn and risk areas.

gitstats hotspots /path/to/repo --top 15

Includes:

• File hotspots (churn score)
• Directory hotspots (aggregated risk)
• Risk map (combined frequency + complexity + ownership)

busfactor

Analyze knowledge distribution and identify risky areas.

gitstats busfactor /path/to/repo

velocity

Analyze development velocity and trends.

gitstats velocity /path/to/repo

Shows:

• Commits per day/week/month
• Trend (accelerating/stable/decelerating)
• Consistency score
• Release rhythm (from tags)
• Codebase evolution (LOC growth over time)
• Sprint cycle detection

complexity

Analyze code complexity and technical debt.

gitstats complexity /path/to/repo

Shows:

• Technical debt score (0-100)
• God files (too many changes/authors)
• Growing files (rapid expansion)
• Refactoring candidates
• Critical hotspots (high churn + high changes)
• Debt indicators

commits

Analyze commit patterns and quality.

gitstats commits /path/to/repo

Shows:

• Commit type distribution (feat, fix, docs, etc.)
• Conventional commits percentage
• WIP commits
• Large commits (>500 LOC)
• Author breakdown by commit type
• Type evolution over time

workpatterns

Analyze work patterns and team habits.

gitstats workpatterns /path/to/repo

Shows:

• Peak hour and day
• Night owl percentage
• Weekend commits
• Work-life balance score
• Timezone distribution
• Author work styles

health

Analyze repository health and code freshness.

gitstats health /path/to/repo

Shows:

• Health score (0-100)
• Zombie files (single commit, old)
• Legacy files (not touched in months)
• Abandoned directories
• Test metrics (test/code ratio)

collaboration

Analyze team collaboration patterns.

gitstats collaboration /path/to/repo

Shows:

• Collaboration score
• Collaboration pairs (who works together)
• Shared files
• Lone wolves (isolated contributors)
• Knowledge silos

coupling

Analyze file coupling (files that change together).

gitstats coupling /path/to/repo

Shows:

• Coupled file pairs
• Coupling strength
• Potential refactoring opportunities

branches

Analyze branch health and patterns.

gitstats branches /path/to/repo

Shows:

• Branch health score
• Stale branches
• Orphan branches (not merged)
• Naming patterns (GitFlow detection)
• Branch lifecycle metrics
• Workflow type detection

Understanding the Metrics

Churn Score

Measures how frequently a file is modified. High churn indicates:

• Potential technical debt
• Unstable or poorly designed code
• Files that may need refactoring

Formula: commits × log(lines_changed)

Technical Debt Score

0-100 score based on:

• God files percentage
• Growing files percentage
• Refactoring candidates
• High churn files

Critical Hotspots

Files with BOTH high churn AND high changes - the most dangerous areas:

• Risk score (0-100)
• Risk level (critical/high/medium)
• Risk factors (churn, changes, author concentration)

Bus Factor

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

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

Codebase Evolution

Monthly tracking of:

• Lines added/deleted
• Net LOC change
• Files added/deleted
• Cumulative growth

Branch Lifecycle

• Workflow type: gitflow, trunk-based, feature-branch, mixed
• Merge rate: percentage of branches that get merged
• Average lifespan: how long branches live

HTML Dashboard

The HTML output generates an interactive dashboard with:

• Summary statistics cards
• Contributor charts
• Activity heatmaps (day/hour)
• Monthly commit trends
• Velocity metrics with codebase evolution table
• Health score with test metrics
• Technical debt indicators
• Branch lifecycle details
• Critical hotspots table
• Code hotspots and risk map
• Type evolution chart
• Full contributor list

gitstats analyze /path/to/repo -o html -f dashboard.html
open dashboard.html

Project Structure

gitstats/
├── src/
│   ├── cli/
│   │   └── index.ts              # CLI entry point
│   ├── 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
│   ├── outputs/
│   │   ├── cli-renderer.ts       # Terminal output
│   │   ├── html-renderer.ts      # HTML dashboard
│   │   └── json-renderer.ts      # JSON export
│   ├── types/
│   │   └── index.ts              # TypeScript definitions
│   └── utils/
│       ├── exec.ts               # Git command execution
│       └── date.ts               # Date utilities
├── package.json
└── tsconfig.json

License

MIT