gitsumm 1.0.0

Get some insight from your git history — plain-English summaries, hotspots, coupling, and more.

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

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

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