Git repo health aliases for hotspots, bus factor, bug clusters, crisis patterns, and repo summary

README.md

Git Repo Health Aliases

Portable Git aliases for reading a codebase through its history before opening files.

Source

Inspired by Ally Piechowski's post:

• https://piechowski.io/post/git-commands-before-reading-code/?utm_source=tldrnewsletter

What You Get

• git hotspots: Most frequently changed files.
• git busfactor: Contributor concentration with commit-share percentages.
• git bugclusters: Files most often touched by bug-fix style commits.
• git velocity: Commit counts grouped by month.
• git crisis: Revert/hotfix/incident-style commits.
• git riskoverlap: Files that are both high-churn and high-bug.
• git repohealth: Runs the full summary in one shot.

Install

1. Save repo-health.gitconfig somewhere stable on your machine.
2. Add this to ~/.gitconfig:

[include]
	path = /absolute/path/to/repo-health.gitconfig

Or run:

git config --global --add include.path "/absolute/path/to/repo-health.gitconfig"

Usage

git repohealth "1 year ago" 10
git hotspots "6 months ago" 15
git busfactor "12 months ago"
git bugclusters "1 year ago" 10
git velocity "24 months ago"
git crisis "1 year ago"
git riskoverlap "1 year ago" 10

Help aliases are included too:

git repohealth-help
git hotspots-help
git busfactor-help
git bugclusters-help
git velocity-help
git crisis-help
git riskoverlap-help

Notes

• These aliases depend on commit-message quality. bugclusters and crisis are only as good as the words people use in commit messages.
• busfactor uses commit counts, which is directionally useful but not a full ownership model.
• riskoverlap is usually the highest-signal view: files that churn a lot and also show up in fix-style commits.

repo-health.gitconfig

[alias]
	# Top changed files over a time window, excluding deleted paths.
	hotspots = "!f() {\n  since=\"${1:-1 year ago}\"\n  limit=\"${2:-20}\"\n  git log --since=\"$since\" --diff-filter=AMRC --format=format: --name-only \\\n    | sed '/^$/d' \\\n    | sort | uniq -c | sort -nr | head -n \"$limit\"\n}; f"

	# Contributor concentration, with share percentages.
	busfactor = "!f() {\n  since=\"${1:-}\"\n  if [ -n \"$since\" ]; then\n    git shortlog -sn --no-merges --since=\"$since\" HEAD\n  else\n    git shortlog -sn --no-merges HEAD\n  fi | awk '\n    {\n      count=$1\n      $1=\"\"\n      sub(/^[[:space:]]+/, \"\", $0)\n      total += count\n      names[NR]=$0\n      counts[NR]=count\n    }\n    END {\n      for (i = 1; i <= NR; i++) {\n        pct = total ? (counts[i] * 100 / total) : 0\n        printf \"%4d  %5.1f%%  %s\\n\", counts[i], pct, names[i]\n      }\n    }\n  '\n}; f"

	# Files most often touched by bug-fix style commits.
	bugclusters = "!f() {\n  since=\"${1:-1 year ago}\"\n  limit=\"${2:-20}\"\n  pattern=\"fix|bug|broken|defect|incident|hotfix|regression|rollback|revert\"\n  git log -i -E --grep=\"$pattern\" --since=\"$since\" --diff-filter=AMRC --name-only --format=\"\" \\\n    | sed '/^$/d' \\\n    | sort | uniq -c | sort -nr | head -n \"$limit\"\n}; f"

	# Monthly commit counts over a recent window.
	velocity = "!f() {\n  since=\"${1:-24 months ago}\"\n  git log --since=\"$since\" --format=\"%ad\" --date=format:\"%Y-%m\" | sort | uniq -c\n}; f"

	# Incident-style commits that suggest firefighting.
	crisis = "!f() {\n  since=\"${1:-1 year ago}\"\n  pattern=\"revert|hotfix|emergency|rollback|incident|sev[0-9]|regression\"\n  git log --oneline --since=\"$since\" | grep -iE \"$pattern\" || true\n}; f"

	# Files that are both high-churn and high-bug.
	riskoverlap = "!f() {\n  since=\"${1:-1 year ago}\"\n  limit=\"${2:-20}\"\n  pattern=\"fix|bug|broken|defect|incident|hotfix|regression|rollback|revert\"\n  churn=$(mktemp)\n  bugs=$(mktemp)\n  trap 'rm -f \"$churn\" \"$bugs\"' EXIT\n  git log --since=\"$since\" --diff-filter=AMRC --format=format: --name-only \\\n    | sed '/^$/d' \\\n    | sort | uniq -c | awk '{ count=$1; $1=\"\"; sub(/^ +/, \"\", $0); print $0 \"\\t\" count }' > \"$churn\"\n  git log -i -E --grep=\"$pattern\" --since=\"$since\" --diff-filter=AMRC --name-only --format=\"\" \\\n    | sed '/^$/d' \\\n    | sort | uniq -c | awk '{ count=$1; $1=\"\"; sub(/^ +/, \"\", $0); print $0 \"\\t\" count }' > \"$bugs\"\n  awk -F '\\t' '\n    NR==FNR { bug[$1]=$2; next }\n    ($1 in bug) { printf \"%6d churn  %6d bug  %s\\n\", $2, bug[$1], $1 }\n  ' \"$bugs\" \"$churn\" | sort -nr | head -n \"$limit\"\n}; f"

	# One-shot summary of the repo health signals.
	repohealth = "!f() {\n  since=\"${1:-1 year ago}\"\n  limit=\"${2:-10}\"\n  printf \"== Hotspots (%s) ==\\n\" \"$since\"\n  git hotspots \"$since\" \"$limit\"\n  printf \"\\n== Bus Factor (%s) ==\\n\" \"$since\"\n  git busfactor \"$since\"\n  printf \"\\n== Bug Clusters (%s) ==\\n\" \"$since\"\n  git bugclusters \"$since\" \"$limit\"\n  printf \"\\n== Risk Overlap (%s) ==\\n\" \"$since\"\n  git riskoverlap \"$since\" \"$limit\"\n  printf \"\\n== Velocity (24 months ago) ==\\n\"\n  git velocity \"24 months ago\"\n  printf \"\\n== Crisis Patterns (%s) ==\\n\" \"$since\"\n  git crisis \"$since\"\n}; f"

	# Terse usage helpers.
	hotspots-help = "!printf '%s\n' 'git hotspots [since] [limit]' '  Example: git hotspots \"6 months ago\" 15' '  Shows the most frequently changed files.'"
	busfactor-help = "!printf '%s\n' 'git busfactor [since]' '  Example: git busfactor \"12 months ago\"' '  Shows contributors ranked by commit share.'"
	bugclusters-help = "!printf '%s\n' 'git bugclusters [since] [limit]' '  Example: git bugclusters \"1 year ago\" 10' '  Shows files most often touched by fix-style commits.'"
	velocity-help = "!printf '%s\n' 'git velocity [since]' '  Example: git velocity \"24 months ago\"' '  Shows commit counts grouped by month.'"
	crisis-help = "!printf '%s\n' 'git crisis [since]' '  Example: git crisis \"1 year ago\"' '  Shows revert/hotfix/incident-style commits.'"
	riskoverlap-help = "!printf '%s\n' 'git riskoverlap [since] [limit]' '  Example: git riskoverlap \"1 year ago\" 10' '  Shows files that are both high-churn and high-bug.'"
	repohealth-help = "!printf '%s\n' 'git repohealth [since] [limit]' '  Example: git repohealth \"1 year ago\" 10' '  Runs the full repo-health summary using the aliases above.'"