oh-my-gitstats 0.2.3

Git repository commit statistics collector and visualizer

📊 oh-my-gitstats

中文 | English

A Python CLI tool for collecting git commit statistics and visualizing them as interactive HTML charts.

✨ Features

• 🔍 Batch Collection - Scan multiple git repositories recursively
• ⚡ Incremental Sync - Only fetch new commits since last collection
• 📈 Line Charts - Track changes over time with metric & granularity switching
• 🗓️ Calendar Heatmaps - Visualize commit activity with year-based filtering
• 🎯 Aggregated & Individual Views - See combined or per-repo statistics
• 📂 VS Code Integration - Open repo folders directly from the HTML report

🚀 Installation

From PyPI (Recommended)

pip install oh-my-gitstats

From Source (Development)

git clone https://github.com/amomorning/oh-my-gitstats.git
cd oh-my-gitstats
pip install -e .

📖 Usage

1️⃣ Collect Commit Data

Scan a directory for git repositories and export to JSON:

gitstats collect /path/to/repos --output ./data

Options:

Option	Description
-o, --output	Directory to save JSON files (default: ./data)
-q, --quiet	Suppress output messages
--skip	Skip repos that already have a JSON file in the output directory
--check	Check GitHub archive status (requires network; set GITHUB_TOKEN for private repos)

2️⃣ Incremental Sync

You may collect repos from multiple locations into the same data directory. Re-running collect on every location is slow — sync reads the existing JSON files and only fetches new commits for each repo:

# Collect from multiple locations (one-time)
gitstats collect /path/to/work-projects --output ./data
gitstats collect /path/to/personal-projects --output ./data --skip

# Later, update all at once — only new commits
gitstats sync ./data

Options:

Option	Description
-q, --quiet	Suppress output messages
--check	Check GitHub archive status (requires network; set GITHUB_TOKEN for private repos)

3️⃣ Generate Visualization

Create an interactive HTML file from collected data:

gitstats visualize ./data --output ./output/stats.html

Options:

Option	Description
-o, --output	HTML file path (default: ./output/stats.html)

Granularity and metric can be switched dynamically in the generated HTML — no need to regenerate.

🔑 GitHub Token (Optional)

--check queries the GitHub API to check archive status. Without authentication, only public repositories can be checked (rate limit: 60 requests/hour).

If GITHUB_TOKEN is not set, a warning will be printed when using --check.

To check private repositories, set the GITHUB_TOKEN environment variable:

Linux / macOS

export GITHUB_TOKEN=ghp_your_token_here
gitstats sync ./data --check

Windows (PowerShell)

Set for current session:

$env:GITHUB_TOKEN="ghp_your_token_here"
gitstats sync ./data --check

Set permanently via GUI: Settings → System → About → Advanced system settings → Environment Variables → User variables → New

Verify the value:

echo $env:GITHUB_TOKEN

How to get a token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token (classic)
3. Give it a name (e.g. oh-my-gitstats)
4. Under Select scopes, no additional scopes are needed (public repo access is default)
5. To access private repositories, check the repo scope
6. Click Generate token and copy the value (starts with ghp_)

Note: Use Tokens (classic), not Fine-grained tokens. With a token, the rate limit increases to 5,000 requests/hour.

📁 Output

The generated HTML contains:

1. 📈 Line Chart - Changes over time with metric selector (Lines Changed / Commit Count) and granularity selector (Day/Week/Month). Click legend to toggle projects.

2. 🗓️ Aggregate Heatmap - Combined activity across all repos with year selector (All Years / specific year).

3. 📊 Individual Heatmaps - Per-repository calendar views in a responsive grid, each with sync status indicator and a "Continue" / "Archived" button to open in VS Code.

📋 JSON Format

Each repository generates a JSON file:

{
  "repo_name": "my-project",
  "repo_path": "/absolute/path/to/my-project",
  "last_commit_hash": "a1b2c3d4...",
  "sync_status": "synced",
  "is_archived": false,
  "commits": [
    {
      "timestamp": "2024-01-15T10:30:00",
      "additions": 45,
      "deletions": 12
    }
  ]
}

The last_commit_hash field stores the HEAD commit hash at collection time. During sync, repositories with a matching hash are skipped instantly — no git operations needed.

The sync_status field indicates the repository's sync state with its remote:

Status	Description
✅ synced	In sync with remote
✏️ local_changes	Local has uncommitted changes, remote is up-to-date
⬇️ remote_ahead	Local is clean, but remote has new commits
⚠️ diverged	Local has uncommitted changes and remote has new commits
🔒 local_only_clean	No remote configured, local is clean
🔧 local_only_dirty	No remote configured, local has uncommitted changes
⚠️ network_error_clean	Remote exists but fetch failed, local is clean
⚠️ network_error_dirty	Remote exists but fetch failed, local has uncommitted changes

The is_archived field indicates whether the repository is archived on GitHub. Set by --check. Values: true (archived), false (active), null (not checked or check failed). Archived repos show a grayed-out "Archived" button in the visualization.

🔧 Requirements

• Python 3.9+
• click
• gitpython
• pyecharts
• jinja2
• requests