Metadata-Version: 2.4
Name: gitsumm
Version: 1.0.0
Summary: Get some insight from your git history — plain-English summaries, hotspots, coupling, and more.
Author: Kshitiz Yadav
Maintainer: Kshitiz Yadav
License-Expression: MIT
Project-URL: Homepage, https://github.com/kshitizyadav6/gitsumm
Project-URL: Repository, https://github.com/kshitizyadav6/gitsumm
Project-URL: Issues, https://github.com/kshitizyadav6/gitsumm/issues
Project-URL: Changelog, https://github.com/kshitizyadav6/gitsumm/blob/main/CHANGELOG.md
Keywords: git,summary,standup,changelog,cli,developer-tools,code-review,insights
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.25; extra == "ai"
Dynamic: license-file

# gitsumm

*Say it out loud: "get some."* Point it at a repo and get some insight from your
git history, in plain English.

`git log` tells you *what* happened, one line at a time. `gitsumm` tells you the
*story*: how many commits, by whom, when activity peaked, whether momentum is up
or down, and which files only one person has touched (a bus-factor risk). It's
the digest you paste straight into a standup, changelog, or team update.

## Install

```bash
pip install -e .          # core tool (works fully offline)
pip install -e ".[ai]"    # add the optional Anthropic-powered summary
```

Requires Python 3.8+. The only hard dependencies are `typer` and `rich`; the
`anthropic` SDK is an optional extra used only by `--ai`.

## Usage

```bash
gitsumm                 # summarize the last 7 days
gitsumm --days 14       # custom window (alias: -d 14)
gitsumm --standup       # commit subjects grouped by author
gitsumm --hotspots 5    # rank the top N churn hotspots (high-risk files)
gitsumm --coupling      # files that tend to change together (hidden coupling)
gitsumm --verbose       # extra detail, incl. the lowest-hygiene commits (-v)
gitsumm --ai            # add a fluent paragraph via the Anthropic SDK
gitsumm --changelog     # themed changelog (Features / Fixes / Refactors / Other)
gitsumm since v1.0.0    # summarize everything since a tag (or between two tags)
gitsumm since v1.0.0 --changelog   # release notes for a range
gitsumm --version
gitsumm --help
```

### Default summary

```
╭──────────────── gitsumm · myrepo · get some ───────────────╮
│ Got some — 24 commits from 3 contributors in the last 7 days │
│ Most active: Alice (14 commits)                              │
│ Busiest day: Tuesday (9 commits)                             │
│ Files touched: 18                                            │
│ Commit hygiene: 86/100                                       │
│ Hottest file: payments.py — 23 changes, 5 authors. Handle with care. │
│ Momentum: ↑ up 6 vs previous 7 days (18 → 24)                │
│ Heads up — 30% of commits land outside working hours...      │
│                                                              │
│ Bus-factor risk — 3 files touched by a single author:        │
│   • auth.py — only Alice                                     │
│   • billing.py — only Bob                                    │
│   • reports.py — only Alice                                  │
╰──────────────────────────────────────────────────────────────╯
```

The **momentum**, **bus-factor**, and **hottest-file** lines are the point of
the tool — insights a raw log won't give you. Momentum compares this window
against the equal-length window immediately before it. Bus-factor flags files
only one author has touched in the window, busiest first, so knowledge silos
surface. The inline "Hottest file" line names the single highest-risk file (only
when there's real churn). A "Heads up" line flags **work-hours patterns** —
appearing only when a meaningful share of commits land outside working hours
(before 8am / after 8pm) or on weekends, so it reads as a team-health signal
rather than noise. A **commit hygiene** score (0–100) rates workflow health — it
penalizes one-word or vague messages and oversized commits; `--verbose` lists
the worst offenders.

### Churn hotspots — where the heat is

High-churn, multi-author files are where defects concentrate. `--hotspots N`
ranks them in a dedicated panel, scored as `changes × distinct authors`:

```
╭──── hotspots · myrepo · where the heat is ────╮
│   • payments.py — 23 changes · 5 authors · score 115 │
│   • auth.py — 12 changes · 3 authors · score 36      │
│   • api.py — 9 changes · 2 authors · score 18        │
╰────────────────────────────────────────────────╯
```

### Co-change coupling — the usual suspects

Files that almost always commit together are coupled whether the code says so or
not — surfacing undocumented dependencies. `--coupling` reports pairs that
co-occur often enough (and with a high enough ratio) to matter; bulk commits
touching many files are ignored so they don't manufacture false coupling.

```
╭──── usual suspects · myrepo · files that travel together ────╮
│   • auth.py ↔ session.py — change together 90% of the time (9×) │
│   • api.py ↔ schema.py — change together 80% of the time (8×)   │
╰────────────────────────────────────────────────────────────────╯
```

### Standup mode

```
╭─ gitsumm · myrepo · get some standup (in the last 7 days) ─╮
│ Alice (3 commits)                                         │
│   • Add weekly report export                              │
│   • Hash passwords with bcrypt                            │
│   • Add login endpoint                                    │
│                                                           │
│ Bob (1 commit)                                            │
│   • Fix invoice rounding                                  │
╰───────────────────────────────────────────────────────────╯
```

### AI mode

With the `[ai]` extra installed and `ANTHROPIC_API_KEY` set, `--ai` adds a
fluent paragraph above the stats panel:

```
╭───────────────── gitsumm · myrepo · the gist ─────────────────╮
│ Over the past week myrepo saw steady progress: 24 commits    │
│ from three contributors, with Alice driving most of the auth  │
│ work and Tuesday the busiest day. Momentum is up on the prior │
│ week. Heads up — auth.py and reports.py have only been        │
│ touched by Alice, a bus-factor risk worth spreading around.   │
╰───────────────────────────────────────────────────────────────╯
```

`--ai` never breaks the tool: if the `anthropic` SDK isn't installed, the API
key is missing, or the request fails, gitsumm falls back to a deterministic
templated paragraph and prints a short hint explaining why. Set
`GITSUMM_AI_MODEL` to use a model other than the default.

### Themed changelog & tag ranges

`--changelog` groups commits into **Features / Fixes / Refactors / Other** —
fluent release notes when AI is available, a deterministic keyword grouping
when it isn't (same crash-proof fallback as `--ai`). Pair it with the `since`
command to summarize a release instead of a day window:

```
gitsumm since v1.0.0 --changelog          # everything since a tag
gitsumm since v1.0.0 v1.1.0 --changelog   # between two tags
```

```
╭─ gitsumm · myrepo · changelog (since v1.0.0) ─╮
│ Features                                     │
│   • Add user login endpoint                  │
│   • Add billing webhook                      │
│ Fixes                                        │
│   • Fix invoice rounding                     │
│ Refactors                                    │
│   • Refactor reports module                  │
╰──────────────────────────────────────────────╯
```

Every flag above (`--standup`, `--hotspots`, `--coupling`, `--ai`, `--verbose`)
also works with `since`.

## Behavior & guarantees

- **Works fully offline.** AI is an enhancement, never a requirement.
- **Fails friendly.** Not a git repo, no commits in the window, or git not
  installed each produce a clear one-line message and a clean exit — never a
  stack trace.
- **Reads `ANTHROPIC_API_KEY`** from the environment; missing key during `--ai`
  falls back gracefully.

## Project layout

```
gitsumm/
├── main.py        # CLI wiring + output formatting (typer + rich)
├── git_utils.py   # all git/subprocess logic and analysis; returns clean objects
└── ai.py          # optional Anthropic summary, fully isolated and crash-proof
```
