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

New 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

Output Formats

• CLI - Colored terminal output with charts
• JSON - Machine-readable export
• HTML - Interactive dashboard with Chart.js visualizations
• HTML Reports - Individual HTML reports for each analyzer

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

report

Generate all HTML reports in a directory.

gitstats report /path/to/repo -d ./reports

This generates 16 HTML reports + an index page:

• 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
• index.html - Links to all reports

Options:

• -d, --dir <directory> - Output directory (default: ./gitstats-report)

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 -f report.html

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

Options:

• -o, --output <format> - Output format: cli, json (default: cli)
• -f, --file <path> - Save HTML report to file (always shows CLI output)
• -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
gitstats busfactor /path/to/repo -f busfactor.html

velocity

Analyze development velocity and trends.

gitstats velocity /path/to/repo
gitstats velocity /path/to/repo -f velocity.html

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
gitstats complexity /path/to/repo -f complexity.html

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
gitstats commits /path/to/repo -f commits.html

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
gitstats workpatterns /path/to/repo -f workpatterns.html

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
gitstats health /path/to/repo -f health.html

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
gitstats collaboration /path/to/repo -f collaboration.html

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
gitstats coupling /path/to/repo -f coupling.html

Shows:

• Coupled file pairs
• Coupling strength
• Potential refactoring opportunities

branches

Analyze branch health and patterns.

gitstats branches /path/to/repo
gitstats branches /path/to/repo -f branches.html

Shows:

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

burnout

Detect developer burnout risk.

gitstats burnout /path/to/repo
gitstats burnout /path/to/repo -f burnout.html

Shows:

• Team burnout risk score
• Individual developer risk levels
• Risk factors (overtime, weekend work, late nights)
• Recommendations

leaderboard

Gamified contributor statistics.

gitstats leaderboard /path/to/repo
gitstats leaderboard /path/to/repo -f leaderboard.html

Shows:

• Most commits, code contributors, bug hunters
• Feature builders, refactor masters, documentation heroes
• Achievements and badges
• Fun stats (night owl, polyglot, big bang commits)

deadcode

Detect potentially dead or unused code.

gitstats deadcode /path/to/repo
gitstats deadcode /path/to/repo -f deadcode.html

Shows:

• Potentially dead files
• Stale exports
• Unused dependencies
• Recommendations

dependencies

Analyze file dependencies.

gitstats dependencies /path/to/repo
gitstats dependencies /path/to/repo -f dependencies.html

Shows:

• Dependency health score
• Circular dependencies
• Hub files (high connectivity)
• Module clusters

duplicates

Detect code duplication.

gitstats duplicates /path/to/repo
gitstats duplicates /path/to/repo -f duplicates.html

Shows:

• Duplication percentage
• Clone groups
• Potential LOC savings
• Refactoring recommendations

city

3D Code City visualization.

gitstats city /path/to/repo
gitstats city /path/to/repo -f city.html

Generates an interactive 3D visualization where:

• Buildings represent files
• Building height = lines of code
• Building color = file type
• Districts = directories

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

Burnout Risk

Based on:

• Overtime work patterns
• Weekend commits frequency
• Late night coding
• Sprint intensity

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 -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
│   │   ├── 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
│   ├── 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

License

MIT