oh-my-gitstats 0.1.0__tar.gz

oh_my_gitstats-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 amomorning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oh_my_gitstats-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+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

oh_my_gitstats-0.1.0/README.md

@@ -0,0 +1,145 @@
+<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

oh_my_gitstats-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "oh-my-gitstats"
+version = "0.1.0"
+description = "Git repository commit statistics collector and visualizer"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "amomorning", email = "amomorning@gmail.com" },
+]
+keywords = ["git", "statistics", "visualization", "commit", "heatmap", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "click>=8.0",
+    "gitpython>=3.1",
+    "pyecharts>=2.0",
+    "jinja2>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/amomorning/oh-my-gitstats"
+Repository = "https://github.com/amomorning/oh-my-gitstats"
+Issues = "https://github.com/amomorning/oh-my-gitstats/issues"
+
+[project.scripts]
+gitstats = "oh_my_gitstats.cli:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+oh_my_gitstats = ["template.html"]

oh_my_gitstats-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oh_my_gitstats-0.1.0/src/oh_my_gitstats/__init__.py

@@ -0,0 +1,3 @@
+"""oh-my-gitstats: Git repository commit statistics collector and visualizer."""
+
+__version__ = "0.1.0"

oh_my_gitstats-0.1.0/src/oh_my_gitstats/charts.py

@@ -0,0 +1,245 @@
+"""Chart building functions using pyecharts."""
+
+from datetime import datetime
+from typing import List, Dict, Any
+from collections import defaultdict
+
+from pyecharts import options as opts
+from pyecharts.charts import Line, Calendar
+from pyecharts.commons.utils import JsCode
+
+from .constants import METRICS, GRANULARITIES, COLORS
+from .data import aggregate_by_period
+
+
+def build_line_opts(
+    all_data: List[Dict[str, Any]],
+    granularity: str,
+    metric: str
+) -> str:
+    """Build line chart options JSON string.
+
+    Args:
+        all_data: List of repository data.
+        granularity: Time aggregation granularity (day/week/month).
+        metric: "changes" or "commits".
+
+    Returns:
+        JSON string of chart options.
+    """
+    all_periods = set()
+    repo_series = {}
+
+    for repo in all_data:
+        aggregated = aggregate_by_period(repo["commits"], granularity, metric)
+        repo_series[repo["repo_name"]] = aggregated
+        all_periods.update(aggregated.keys())
+
+    sorted_periods = sorted(all_periods)
+
+    line = Line()
+    line.add_xaxis(sorted_periods)
+
+    for idx, (repo_name, data) in enumerate(repo_series.items()):
+        y_data = [data.get(period, 0) for period in sorted_periods]
+        line.add_yaxis(
+            series_name=repo_name,
+            y_axis=y_data,
+            color=COLORS[idx % len(COLORS)],
+            is_smooth=True,
+            label_opts=opts.LabelOpts(is_show=False),
+        )
+
+    y_name = "Lines Changed" if metric == "changes" else "Commits"
+
+    line.set_global_opts(
+        tooltip_opts=opts.TooltipOpts(
+            trigger="axis",
+            formatter=JsCode(
+                "function(params){"
+                "var tip=params[0].axisValueLabel;"
+                "params.forEach(function(p){"
+                "if(p.value[1])tip+='<br/>'+p.marker+p.seriesName+': '+p.value[1];"
+                "});"
+                "return tip;}"
+            )
+        ),
+        legend_opts=opts.LegendOpts(
+            type_="scroll",
+            selected_mode="multiple"
+        ),
+        xaxis_opts=opts.AxisOpts(
+            type_="category",
+            axislabel_opts=opts.LabelOpts(rotate=45)
+        ),
+        yaxis_opts=opts.AxisOpts(name=y_name, type_="value"),
+        datazoom_opts=[
+            opts.DataZoomOpts(type_="inside"),
+            opts.DataZoomOpts(type_="slider")
+        ]
+    )
+
+    return line.dump_options()
+
+
+def build_agg_heatmap_opts(
+    all_data: List[Dict[str, Any]],
+    date_range: tuple[str, str],
+    metric: str
+) -> str:
+    """Build aggregate heatmap options JSON string.
+
+    Args:
+        all_data: List of repository data.
+        date_range: Tuple of (start_date, end_date).
+        metric: "changes" or "commits".
+
+    Returns:
+        JSON string of chart options.
+    """
+    daily_data = defaultdict(int)
+    for repo in all_data:
+        for commit in repo["commits"]:
+            ts = datetime.fromisoformat(commit["timestamp"])
+            date_str = ts.strftime("%Y-%m-%d")
+            if metric == "commits":
+                daily_data[date_str] += 1
+            else:
+                daily_data[date_str] += commit["additions"] + commit["deletions"]
+
+    calendar_data = [[date, value] for date, value in sorted(daily_data.items())]
+
+    calendar = Calendar(init_opts=opts.InitOpts(width="100%", height="300px"))
+    calendar.add(
+        series_name="",
+        yaxis_data=calendar_data,
+        calendar_opts=opts.CalendarOpts(
+            pos_left="100px",
+            pos_right="50px",
+            pos_top="50px",
+            pos_bottom="20px",
+            range_=date_range,
+            yearlabel_opts=opts.CalendarYearLabelOpts(is_show=True),
+            monthlabel_opts=opts.CalendarMonthLabelOpts(is_show=True),
+            daylabel_opts=opts.CalendarDayLabelOpts(is_show=True),
+        )
+    )
+
+    unit = "lines" if metric == "changes" else "commits"
+    calendar.set_global_opts(
+        visualmap_opts=opts.VisualMapOpts(
+            max_=max(daily_data.values()) if daily_data else 100,
+            min_=0,
+            orient="horizontal",
+            is_piecewise=False,
+            pos_left="100px",
+            pos_bottom="0px",
+        ),
+        tooltip_opts=opts.TooltipOpts(formatter=JsCode(
+            f"function(p){{return p.data[0] + ': ' + p.data[1] + ' {unit}'}}"
+        ))
+    )
+
+    return calendar.dump_options()
+
+
+def build_ind_heatmap_opts(
+    all_data: List[Dict[str, Any]],
+    date_range: tuple[str, str],
+    metric: str
+) -> List[str]:
+    """Build individual heatmap options JSON string list.
+
+    Args:
+        all_data: List of repository data.
+        date_range: Tuple of (start_date, end_date).
+        metric: "changes" or "commits".
+
+    Returns:
+        List of JSON strings, one per repository.
+    """
+    options_list = []
+
+    for repo in all_data:
+        daily_data = defaultdict(int)
+        for commit in repo["commits"]:
+            ts = datetime.fromisoformat(commit["timestamp"])
+            date_str = ts.strftime("%Y-%m-%d")
+            if metric == "commits":
+                daily_data[date_str] += 1
+            else:
+                daily_data[date_str] += commit["additions"] + commit["deletions"]
+
+        calendar_data = [[date, value] for date, value in sorted(daily_data.items())]
+
+        calendar = Calendar(init_opts=opts.InitOpts(width="100%", height="200px"))
+        calendar.add(
+            series_name="",
+            yaxis_data=calendar_data,
+            calendar_opts=opts.CalendarOpts(
+                pos_left="100px",
+                pos_right="50px",
+                pos_top="30px",
+                pos_bottom="10px",
+                range_=date_range,
+                yearlabel_opts=opts.CalendarYearLabelOpts(is_show=False),
+                monthlabel_opts=opts.CalendarMonthLabelOpts(is_show=True),
+                daylabel_opts=opts.CalendarDayLabelOpts(is_show=False),
+            )
+        )
+
+        max_val = max(daily_data.values()) if daily_data else 100
+        unit = "lines" if metric == "changes" else "commits"
+        calendar.set_global_opts(
+            visualmap_opts=opts.VisualMapOpts(
+                max_=max_val,
+                min_=0,
+                orient="horizontal",
+                is_piecewise=False,
+                pos_left="100px",
+                pos_bottom="0px",
+            ),
+            tooltip_opts=opts.TooltipOpts(formatter=JsCode(
+                f"function(p){{return p.data[0] + ': ' + p.data[1] + ' {unit}'}}"
+            ))
+        )
+
+        options_list.append(calendar.dump_options())
+
+    return options_list
+
+
+def build_line_js_obj(all_data: List[Dict[str, Any]]) -> str:
+    """Build JS object string for line chart data (all metric x granularity combos)."""
+    parts = []
+    for metric in METRICS:
+        gran_parts = []
+        for gran in GRANULARITIES:
+            opts_json = build_line_opts(all_data, gran, metric)
+            gran_parts.append(f'"{gran}":{opts_json}')
+        parts.append(f'"{metric}":{{{",".join(gran_parts)}}}')
+    return "{" + ",".join(parts) + "}"
+
+
+def build_heatmap_js_obj(
+    all_data: List[Dict[str, Any]],
+    date_range: tuple[str, str],
+    years: List[str]
+) -> str:
+    """Build JS object string for heatmap data (all metric x year combos)."""
+    year_ranges: Dict[str, tuple[str, str]] = {"all": date_range}
+    for year in years:
+        year_ranges[year] = (f"{year}-01-01", f"{year}-12-31")
+
+    parts = []
+    for metric in METRICS:
+        year_parts = []
+        for year_key, year_range in year_ranges.items():
+            agg = build_agg_heatmap_opts(all_data, year_range, metric)
+            ind_list = build_ind_heatmap_opts(all_data, year_range, metric)
+            ind_str = ",".join(ind_list)
+            year_parts.append(
+                f'"{year_key}":{{"aggregate":{agg},"individual":[{ind_str}]}}'
+            )
+        parts.append(f'"{metric}":{{{",".join(year_parts)}}}')
+    return "{" + ",".join(parts) + "}"