Metadata-Version: 2.4
Name: git-insights-cli
Version: 1.0.0
Summary: Analyze git repositories for commit patterns, contributor stats, code churn, and team productivity insights
Project-URL: Homepage, https://github.com/SanjaySundarMurthy/git-insights
Project-URL: Repository, https://github.com/SanjaySundarMurthy/git-insights
Project-URL: Issues, https://github.com/SanjaySundarMurthy/git-insights/issues
Author-email: Sanjay S <sanjaysundarmurthy@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,cli,code-churn,commits,contributors,devops,git,insights,productivity,reports
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 📊 git-insights

[![PyPI version](https://badge.fury.io/py/git-insights-cli.svg)](https://pypi.org/project/git-insights-cli/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Analyze git repositories for commit patterns, contributor stats, code churn, and team productivity insights.**

Turn your git history into actionable insights. `git-insights` analyzes commit patterns, identifies code hotspots, calculates bus factor, scores repository health, and generates beautiful reports — all from the command line.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 📈 **Commit Analytics** | Total commits, lines changed, merge ratios, trends |
| 👥 **Contributor Stats** | Leaderboard with commits, lines, active days per author |
| 🔥 **File Hotspots** | Identify most churned files (high change + high commits) |
| 📅 **Day Distribution** | Which days of the week see the most commits |
| 🕐 **Hour Heatmap** | Activity pattern by hour of day |
| 📊 **Monthly Trends** | Commit frequency over time with bar charts |
| 🏥 **Health Score** | 0-100 repository health grade (A+ to F) |
| 🚌 **Bus Factor** | How many contributors cover 50% of commits |
| 📋 **File Types** | Changes breakdown by file extension |
| 🌐 **HTML Reports** | Beautiful dark-themed dashboards |
| 📄 **JSON Export** | Machine-readable output for CI/CD integration |
| ⏰ **Time Filtering** | Analyze specific date ranges with `--since`/`--until` |

---

## 📦 Installation

```bash
pip install git-insights-cli
```

---

## 🚀 Quick Start

```bash
# Full analysis of current repo
git-insights analyze .

# Generate HTML dashboard
git-insights analyze . --html report.html

# Last 6 months only
git-insights analyze . --since "6 months ago"

# Quick summary
git-insights summary .

# Contributor leaderboard
git-insights contributors .

# File hotspots
git-insights hotspots .

# Activity patterns
git-insights activity .
```

---

## 📖 Commands

### `analyze` — Full repository analysis

```bash
git-insights analyze <PATH> [OPTIONS]

Options:
  --since TEXT   Start date (e.g., '2024-01-01', '6 months ago')
  --until TEXT   End date
  --html PATH    Export HTML dashboard report
  -j PATH        Export JSON report
```

Generates comprehensive analysis including:
- Summary stats (commits, lines, age, bus factor)
- Top contributors leaderboard
- Day-of-week distribution with bar charts
- Hour-of-day activity heatmap
- File hotspot table (churn score ranking)
- Monthly commit trend
- File type breakdown
- Health score (A+ to F grade)

### `contributors` — Contributor leaderboard

```bash
git-insights contributors <PATH> [--top N]
```

### `hotspots` — Most churned files

```bash
git-insights hotspots <PATH> [--top N]
```

Files with high churn scores (changes × commits) are potential refactoring candidates.

### `activity` — Commit activity patterns

```bash
git-insights activity <PATH>
```

Shows day-of-week distribution and hour-of-day heatmap.

### `summary` — Quick health check

```bash
git-insights summary <PATH>
```

---

## 🏥 Health Score

The health score (0-100) considers:

| Factor | Bonus |
|--------|-------|
| 3+ contributors | +10 |
| Last commit < 7 days | +15 |
| Last commit < 30 days | +10 |
| Bus factor ≥ 3 | +10 |
| ≥ 1 commit/day avg | +10 |
| Healthy merge ratio | +5 |

Grades: **A+** (90+), **A** (80+), **B** (70+), **C** (60+), **D** (50+), **F** (<50)

---

## 📊 HTML Dashboard

```bash
git-insights analyze . --html report.html
```

The dark-themed dashboard includes:
- **Summary cards** — commits, contributors, lines, bus factor, health grade
- **Contributor table** — ranked by commits with add/delete stats
- **Day distribution** — bar chart showing weekday vs weekend patterns
- **Hour heatmap** — 24-hour activity visualization
- **File hotspots** — most churned files with churn scores
- **Monthly trend** — commit frequency over time
- **File types** — changes by extension

---

## 🔄 CI/CD Integration

### JSON Output

```bash
git-insights analyze . -j insights.json
```

Returns structured JSON with all metrics for dashboards or monitoring.

### GitHub Actions

```yaml
- name: Git Insights
  run: |
    pip install git-insights-cli
    git-insights analyze . -j insights.json --html report.html
```

---

## 🧪 Development

```bash
git clone https://github.com/SanjaySundarMurthy/git-insights.git
cd git-insights
pip install -e ".[dev]"
pytest tests/ -v
ruff check .
```

---

## 📋 Requirements

- Python 3.10+
- Git (accessible via command line)
- click >= 8.0
- rich >= 13.0

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 👤 Author

**Sanjay S** — [GitHub](https://github.com/SanjaySundarMurthy) · [PyPI](https://pypi.org/user/sanjaysundarmurthy/)

---

## 🏆 Other Tools

| Tool | Description | PyPI |
|------|-------------|------|
| [secret-scanner](https://github.com/SanjaySundarMurthy/secret-scanner) | Credential & secret leak detector | [secret-scanner-cli](https://pypi.org/project/secret-scanner-cli/) |
| [docker-lens](https://github.com/SanjaySundarMurthy/docker-lens) | Dockerfile analyzer & optimizer | [docker-lens-cli](https://pypi.org/project/docker-lens-cli/) |
| [yaml-doctor](https://github.com/SanjaySundarMurthy/yaml-doctor) | YAML linter for K8s, Compose, GHA | [yaml-doctor-cli](https://pypi.org/project/yaml-doctor-cli/) |
