git-commit-theme-analyzer

name	git-commit-theme-analyzer
description	Analyze git commit history to extract themes, patterns, and insights. Groups commits by topic, identifies key contributors, and surfaces trends over time. Useful for changelog generation, retrospectives, and understanding project evolution. Trigger keywords: analyze commits, commit patterns, theme analysis, contributor stats, git insights, talk material, commit narrative.
license	MIT
metadata	{"version":"1.1.1","hermes":{"tags":[],"related_skills":[]}}

Git Commit Theme Analyzer

Extract meaningful patterns from git commit history. Goes beyond simple statistics to identify themes, trends, and contributor focus areas.

Basic Usage

Single Repo Analysis

cd /path/to/repo

# Recent activity (time-based)
git log --since="7 days ago" --format="%s"

# By author
git log --author="Name" --format="%s" -50

# By file/path
git log --format="%s" -- path/to/component

Theme Extraction Patterns

Pattern	Search Terms
Performance	speedup|fast|optim|performance|cache|memory
Security	security|xss|inject|travers|vulnerab|cve|fix.*secur
Refactoring	refactor|cleanup|simplif|extract|rename
Bug Fixes	fix|bug|issue|crash|error|broken
Features	add|feature|support|implement|new
Tests	test|spec|coverage|ci|flaky
Documentation	doc|readme|comment|guide|changelog
Dependencies	bump|update|upgrade|dependabot|package

Advanced Analysis

Contributor Focus Areas

# Commit count per author
git log --format="%an|%s" --since="30 days ago" | \
  awk -F'|' '{print $1}' | sort | uniq -c | sort -rn

# Filter by author to see their themes
git log --author="Jean Boussier" --format="%s" --since="30 days ago"

Component Activity

# Which directories changed most
git log --since="30 days ago" --name-only --pretty=format: | \
  grep -v '^$' | sort | uniq -c | sort -rn | head -20

Time-Based Patterns

# Commits by day of week
git log --format="%ad" --date=format:"%u %a" | sort | uniq -c

# Commits by hour
git log --format="%ad" --date=format:"%H" | sort | uniq -c

Multi-Repo Analysis

When analyzing across multiple repositories:

1. Use absolute paths with git -C <path>
2. Normalize commit messages for comparison
3. Track cross-repo patterns (e.g., shared dependencies)

Narrative Extraction: From Commits to Story

When the goal is producing talk material, retrospectives, or case studies:

Per-Month Breakdown with Accurate Boundaries

Two approaches — quick count (faster, approximate) and exact count (more precise at boundaries):

# QUICK: per-month counts (approximate — may shift commits at month boundaries)
git log deploy --since="2025-02-01" --format="%ad" --date=format:"%Y-%m" | sort | uniq -c | sort -t'-' -k1,1n -k2,2n

# EXACT: per-month counts with calendar-accurate boundaries
for month in 2025-02 2025-03 2025-04 2025-10 2025-11 2025-12 2026-01 2026-02 2026-03 2026-04; do
  start="${month}-01"
  end=$(date -d "$start +1 month" '+%Y-%m-%d')
  count=$(git log deploy --since="$start" --until="$end" --oneline | wc -l)
  echo "$month: $count"
done

date -d is GNU (nix-managed machines put GNU date first in PATH, so this is the form that runs here). On stock macOS without nix, use the BSD binary explicitly: end=$(/bin/date -j -v+1m -f '%Y-%m-%d' "${start}" '+%Y-%m-%d') — bare date -j fails when GNU date shadows it.

Pulling Commits from Non-Default Branches

# Pull from a specific remote branch (not locally checked out)
git log origin/rails-upgrade --since="2025-05-01" --until="2025-11-01" --format="%ad %s" --date=short

# List all branches matching a prefix
git branch -a | grep -i "theme-prefix"

Do NOT assume all work landed on the default branch. Check git branch -a for branch naming patterns before declaring a period barren.

Pitfall: Branch Isolation ≠ Secrecy

When discovering a long-lived branch with heavy activity while the default branch was quiet:

• Do NOT frame as "nobody knew" or "hidden work." Isolated branches are standard engineering discipline for migrations too involved for mainline.
• Do NOT imply the engineer was being opaque. The most common answer: they isolated risky work to iterate aggressively without destabilizing production.
• Report it as: "The migration ran on an isolated branch — AI made that isolation strategy practical."

Identifying Forensic Sequences

Look for consecutive commit clusters tracking a single problem:

• Sequential markers (Phase 4.156, Phase 4.157, ...)
• Diagnostic logging commits (Add diagnostic logging for...)
• Revert markers (a commit + its revert, indicating a dead-end hypothesis)

These clusters are the richest narrative material — they show the real debugging arc.

Cross-Cutting Patterns

After per-month breakdown, scan for recurring patterns across eras:

• Fix → Capture → Lint: bug fixed → skill created → linter prevents recurrence
• Remove, Don't Add: best fix deletes code (AI won't volunteer this)
• Tooling Begets Tooling: meta-tools built on top of the workflow itself

Full methodology with detection heuristics in references/cross-cutting-pattern-extraction.md.

Output Structure

Produce two documents:

1. Narrative document — organized by era/phase with anecdotes and context
2. Reference document — raw commit-level data organized by theme, with forensic sequences fully listed

Both cite git log as source with exact branch and date range.