Metadata-Version: 2.4
Name: oh-my-gitstats
Version: 0.1.0
Summary: Git repository commit statistics collector and visualizer
Author-email: amomorning <amomorning@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/amomorning/oh-my-gitstats
Project-URL: Repository, https://github.com/amomorning/oh-my-gitstats
Project-URL: Issues, https://github.com/amomorning/oh-my-gitstats/issues
Keywords: git,statistics,visualization,commit,heatmap,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: pyecharts>=2.0
Requires-Dist: jinja2>=3.0
Dynamic: license-file

<div align="center">



# 📊 oh-my-gitstats

[中文](README.zh-CN.md) | English

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

</div>

![Line Chart](imgs/linechart.png)
![Heatmap](imgs/heatmap.png)

## ✨ 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)

```bash
pip install oh-my-gitstats
```

### From Source (Development)

```bash
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:

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

**Options:**

| Option | Description |
|--------|-------------|
| `-o, --output` | Directory to save JSON files (default: `./data`) |
| `-q, --quiet` | Suppress output messages |

### 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:

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

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

**Options:**

| Option | Description |
|--------|-------------|
| `-q, --quiet` | Suppress output messages |

### 3️⃣ Generate Visualization

Create an interactive HTML file from collected data:

```bash
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.

## 📁 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 an "Open Folder" button to open in VS Code.

![alt text](imgs/repo.png)


## 📋 JSON Format

Each repository generates a JSON file:

```json
{
  "repo_name": "my-project",
  "repo_path": "/absolute/path/to/my-project",
  "last_commit_hash": "a1b2c3d4...",
  "sync_status": "synced",
  "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 |

## 🔧 Requirements

- Python 3.9+
- click
- gitpython
- pyecharts
- jinja2
