English | 日本語

---

gitpulse is a Python CLI that analyzes git history locally and renders repository health metrics as rich terminal dashboards. No SaaS required, no API keys — works entirely offline with any git repository.

Features

• Commit Velocity — frequency heatmaps, trend detection, peak activity identification
• Hot Files — rank files by change frequency and code churn
• Branch Comparison — compare refs with ahead/behind stats and diff summaries
• Health Score — composite repository health with configurable checks and CI integration
• Author Breakdown — contributor stats, activity patterns, distribution charts
• Multiple Output Formats — rich tables, JSON, CSV

Installation

From PyPI (recommended)

pip install gitpulse

From Source

git clone https://github.com/izag8216/gitpulse.git
cd gitpulse
pip install -e .

Quick Start

# Analyze commit velocity for the last 30 days
gitpulse analyze

# Show top 20 hot files with churn threshold
gitpulse hotfiles --top 20 --churn-threshold 0.3

# Compare branches
gitpulse compare main..feature --summary

# Repository health score
gitpulse health --checks all --fail-below 70

# Author contributions
gitpulse authors --top 10 --pie

Commands

Command	Description	Example
analyze	Commit velocity dashboard	gitpulse analyze --period 90d
hotfiles	Hot file & churn ranking	gitpulse hotfiles --top 20 --ext py,js
compare	Branch/ref comparison	gitpulse compare main..feature
health	Repository health score	gitpulse health --output json
authors	Author contribution breakdown	gitpulse authors --pie

Global Options

Option	Description
--repo PATH	Analyze repository at PATH (default: current directory)
--period	Analysis period: 7d, 30d, 90d, 1y, all
--since / --until	Explicit date range (ISO 8601)
--branch	Analyze specific branch
--output	Output format: table, json, csv
--no-color	Disable colored terminal output
--verbose	Enable debug logging

CI Integration

Use --fail-below to gate deployments based on repository health:

- name: Repository Health Check
  run: gitpulse health --fail-below 70 --output json

Output Examples

analyze (table)

╭──────────────────────────────────────────────────────────╮
│ Commit Velocity                                          │
│ Total: 47 commits | Active days: 18 | Quiet days: 12    │
│ Trend: increasing (+23.5%)                               │
╰──────────────────────────────────────────────────────────╯
Peak day: 2024-01-15 (6 commits)

hotfiles (table)

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━┳━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ File                ┃ Commits ┃ +  ┃ -  ┃ Churn ┃ Ratio ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━╇━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━┩
│ src/core/engine.py  │ 23      │ 450│ 120│ 570   │ 24.78 │ active │
│ tests/test_cli.py   │ 18      │ 890│ 45 │ 935   │ 51.94 │ active │
└─────────────────────┴─────────┴────┴────┴───────┴───────┴────────┘

Development

# Setup
git clone https://github.com/izag8216/gitpulse.git
cd gitpulse
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Lint & format
ruff check src tests
ruff format src tests

# Type check
mypy src

# Test with coverage
pytest --cov=gitpulse --cov-report=term-missing

Architecture

CLI Layer (click)  →  Core Engine  →  Analysis Modules
                         │                ├── velocity.py
                    fetcher.py            ├── hotfiles.py
                    reporter.py           ├── churn.py
                                          ├── authors.py
                                          └── health.py

License

MIT License — see LICENSE for details.

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR process.

---

_{Built with yusaku — research-driven OSS builder}