Repo Statter

Repo Statter is a Git repository analysis tool designed to generate insightful, interactive HTML reports. It provides detailed statistics about your codebase, helping you understand its evolution and characteristics.

Note: This tool is designed for projects of all sizes with intelligent caching for performance. Use --max-commits to limit analysis for very large repositories.

Installation

Install from npm

npm install -g repo-statter

Install from source

Alternatively, you can clone the repository and run it directly:

Prerequisites

• Node.js (version 18 or higher)
• Git

Setup (from source)

1. Clone the repository:

   git clone https://github.com/nickpomfret/repo-statter.git
   cd repo-statter

2. Install dependencies:

   npm install

Generating Reports

You can generate reports in two modes:

Basic Usage

# If installed globally
repo-statter /path/to/your/repo

# If running from source
npm run analyse -- /path/to/your/repo

Output:

• dist/repo-statter.html - Interactive HTML report (default location)

CLI Reference

The repo-statter command line interface supports the following options:

repo-statter [repo-path] [options]

Arguments

• [repo-path] - Repository path to analyze (defaults to current directory)

Options

• -r, --repo <path> - Repository path (alternative to positional argument)
• -o, --output <dir> - Output directory for the report (default: "dist")
• --output-file <filename> - Custom output filename (overrides default naming)
• --max-commits <number> - Analyze only the N most recent commits (improves performance for large repos)
• --no-cache - Disable caching (always do full scan)
• --clear-cache - Clear existing cache before running
• --config-file <path> - Path to custom configuration file
• --export-config <path> - Export default configuration to specified file
• --force - Force overwrite existing files when exporting configuration
• -h, --help - Display help information
• -V, --version - Display version number

Examples

# Basic usage
repo-statter                           # Analyze current directory
repo-statter /path/to/repo             # Analyze specific repository

# Custom output
repo-statter . --output reports        # Custom output directory
repo-statter . --output-file my-report # Custom filename (adds .html)

# Performance tuning
repo-statter . --max-commits 500       # Analyze only recent commits
repo-statter . --no-cache              # Disable caching
repo-statter . --clear-cache           # Clear cache first

# Configuration
repo-statter --export-config config.json    # Export default config
repo-statter --config-file config.json      # Use custom config
repo-statter --export-config config.json --force  # Overwrite existing

# Real-world examples
# Large repository with performance optimization
repo-statter ~/projects/linux-kernel --max-commits 10000 --output kernel-analysis

# Team project with custom settings
repo-statter . --config-file team-config.json --output weekly-report

# CI/CD integration
repo-statter $REPO_PATH --output-file build-$BUILD_NUMBER --no-cache

# Quick analysis of recent changes
repo-statter . --max-commits 100 --output-file recent-changes

# If running from source, use npm:
npm run analyse -- /path/to/repo --output reports

Notes

• The --max-commits option analyzes the most recent N commits, which can significantly improve performance for large repositories. Note that cumulative statistics (like total lines of code) will be relative to the analyzed period, not the full repository history
• The --output-file option allows you to specify a custom filename, automatically adding .html extension if not provided
• When using npm scripts, remember to use -- before passing options to separate npm arguments from script arguments
• Output paths are relative to the current working directory
• Use --export-config to create a configuration file you can edit, then --config-file to use it
• The exported configuration file contains all available settings with their default values

Configuration Files

Repo Statter supports custom configuration files for easy customization of analysis settings:

Creating a Configuration File

Export the default configuration to see all available options:

# Export default configuration
repo-statter --export-config my-config.json

# This creates a JSON file with all available settings and their defaults

Using a Configuration File

# Use your custom configuration
repo-statter --config-file my-config.json

# Configuration files can be combined with other options
repo-statter /path/to/repo --config-file my-config.json --output reports

Configuration Categories

The exported configuration file includes settings for:

• Analysis: Commit limits, byte estimation, time series thresholds
• Word Cloud: Size, word limits, display parameters
• Charts: Dimensions, limits for various chart types
• File Heat: Recency decay, weighting factors, display limits
• Performance: Caching, progress reporting settings
• Exclusions: File patterns to ignore during analysis
• File Types: Extension mappings and binary file detection
• Text Analysis: Stop words for text processing
• File Categories: Patterns for categorizing files
• Commit Filters: Patterns for filtering merge/automated commits

Example Workflow

# 1. Export the default configuration
repo-statter --export-config project-config.json

# 2. Edit project-config.json to customize settings
#    For example, increase word cloud size:
#    "wordCloud": { "maxWords": 200, "minWordLength": 4 }

# 3. Use your customized configuration
repo-statter --config-file project-config.json

Performance Caching

Repo Statter includes intelligent caching to dramatically speed up subsequent runs on the same repository:

• First run: Processes all commits and saves processed data to cache
• Subsequent runs: Only processes new commits since last run (50-90% faster)
• Cache location: System temp directory (/tmp/repo-statter-cache/ on Unix systems)
• Cache invalidation: Automatic based on repository changes

Cache Management

# Normal run with caching (default)
repo-statter

# Disable caching (always do full scan)
repo-statter --no-cache

# Clear cache and regenerate (useful after git history changes)
repo-statter --clear-cache

Performance Impact

• Large repositories: 50-90% speed improvement on subsequent runs
• Small repositories: 20-40% speed improvement
• Cache overhead: Minimal (1-5% slower on first run)
• Incremental updates: Near-instant for repositories with few new commits

Features

• Comprehensive Git Analysis: Analyzes complete commit history with line-by-line statistics.
• Interactive Visualizations: Beautiful charts showing commit activity, contributor statistics, file type distribution, and lines of code growth.
• Intelligent Caching: Dramatically speeds up subsequent runs with incremental processing (50-90% faster).
• Self-Contained Reports: Generates standalone HTML files with embedded data and charts, requiring no external dependencies to view.
• Flexible Output: Choose between quick builds or structured analysis output.
• Zero Runtime Dependencies: Reports work offline with no external dependencies.

Report Contents

The generated report includes:

Key Statistics

• Total commits
• Total lines of code
• Top contributor
• Generation date

Interactive Charts

1. Commit Activity Over Time - Area chart showing daily commit frequency
2. Top Contributors - Bar chart of most active contributors
3. Lines of Code Growth - Cumulative lines of code over project lifetime
4. File Type Distribution - Donut chart showing code distribution by language

Advanced Features

• Word Cloud: Visual representation of commit messages and code content
• File Heat Map: Shows most frequently changed files with recency weighting
• Top Files: Charts showing largest and most active files
• Award System: Recognizes contributors with various achievement badges
• Time Series Analysis: Detailed commit activity patterns over time

Development

Tech Stack

• Runtime: Node.js with TypeScript
• Git Integration: simple-git
• Charts: ApexCharts (embedded in output)
• Styling: Bootstrap 5 (embedded in output)

Project Structure

repo-statter/
├── src/
│   ├── index.ts           # Main entry point and CLI
│   └── report/
│       ├── template.html  # Report HTML template
│       └── renderer.ts    # Chart rendering logic
├── docs/
│   └── todo/             # Project documentation and tasks
├── tests/                # Test files
└── package.json          # Project configuration

Running Tests

npm test                  # Run tests once
npm run test:coverage    # Run tests with coverage
npm run test:report      # Generate report from test repo (reuses existing or creates new)
npm run test:clean       # Clean up persistent test repository

Type Checking

npm run typecheck        # Run TypeScript type checking

Development Workflow

For rapid development and testing:

# First time or after cleanup
npm run test:report      # Creates test repo and generates report

# Subsequent runs (much faster - reuses existing test repo)
npm run test:report      # Analyzes existing test repo

# When you need a fresh test repo
npm run test:clean       # Remove persistent test repo
npm run test:report      # Creates new test repo and generates report

The test report is always generated at dist/test-repo-analysis.html for consistent access.

Requirements

• Node.js 18+ (for native fetch support)
• Git repository to analyze
• Write access to create output directories

Output Examples

HTML Report

The HTML report is a beautiful dashboard that works entirely offline. It includes:

• Responsive design that works on desktop and mobile
• Interactive charts with hover tooltips
• Professional styling with smooth animations
• Zero external dependencies - everything is embedded

Report Features

The generated HTML report includes:

• Repository Overview: Total commits, lines of code, contributors, and key metrics
• Interactive Charts: Zoomable time series, filterable contributor data
• Word Clouds: From commit messages and file content
• File Analytics: Heat maps, top files by size and activity
• Contributor Awards: Achievement badges for various contributions
• Responsive Design: Works on desktop, tablet, and mobile devices
• Offline Ready: No external dependencies, works without internet

Future Enhancements

See the docs/todo/ directory for planned features including:

• Code churn analysis
• Commit message word clouds
• Interactive filtering by date/author
• File heatmaps
• Enhanced visualizations

License

MIT License - see LICENSE file for details.

Contributing

This is a private project. See docs/todo/ for development tasks and guidelines.