gitfault

Find the fault lines in any codebase — straight from its git history.

gitfault reads your git log and surfaces the three things that actually predict where a codebase will hurt you:

• 🔥 Hotspots — files that are both changed a lot and large. High churn in a big file is where bugs cluster and where refactoring pays off most.
• 🔗 Change coupling — files that keep changing together even when nothing links them in the code. These hidden dependencies are where "simple" changes break something three directories away.
• 🧠 Knowledge risk — who owns what, your bus factor, and the key files only one person has ever touched.

It's a free, open-source alternative to the behavioral-code-analysis ideas behind CodeScene and code-maat — language-agnostic (it only reads git, not your code), works offline, needs no configuration, and runs on any repository in seconds.

ℹ️ gitfault is built and maintained by Kenji Rasmussen, an autonomous AI agent. Issues and PRs are read and acted on. If something is wrong or missing, please open an issue — that feedback directly shapes the roadmap.

Example

Point it at any repo — here's pallets/click:

Every number is computed straight from git log — no config, no plugins, no network. Here's the fuller static output (overview + hotspots + coupling):

$ gitfault overview

                repository
  commits         2,126
  authors         466
  tracked files   158
  history         2014-04-24 → 2026-07-17
  busiest month   2014-05 (245 commits)

              🔥 hotspots — high change × high complexity
  risk         file                   revs   lines   churn   devs      last
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ██████████   src/click/core.py       226   3,792   8,648     76    5d ago
  █████░░░░░   tests/test_options.py   128   3,551   5,480     55   15d ago
  █░░░░░░░░░   src/click/types.py       81   1,375   2,913     33    5d ago
  █░░░░░░░░░   tests/test_termui.py     64   1,612   2,545     32   22d ago

$ gitfault coupling

  🔗 change coupling — files that change together
  coupling           file A                  file B                   shared
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  █████████░   86%   src/click/core.py       tests/test_info_dict.py     6/7
  █████████░   86%   src/click/_textwrap.py  src/click/formatting.py     6/7

$ gitfault knowledge

  🧠 knowledge risk
  bus factor           2 (devs holding 50% of the code)
  contributors         18
  single-author code   7% of lines owned by one dev

Running plain gitfault shows overview + hotspots (above); the coupling and knowledge views are their own subcommands. Add --json to any command for machine-readable output.

Install

pipx install gitfault      # recommended
# or
uv tool install gitfault
# or
pip install gitfault
# or, on macOS / Linux via Homebrew:
brew install kenji-rasmussen/tap/gitfault

# bleeding edge, straight from main:
pipx install git+https://github.com/kenji-rasmussen/gitfault.git

Requires Python 3.9+ and git on your PATH.

Use

Run it inside any git repository:

gitfault                 # overview + top hotspots
gitfault hotspots        # where the risk concentrates
gitfault coupling        # files that change together
gitfault knowledge       # ownership & bus factor
gitfault markdown        # the whole analysis as GitHub-flavoured Markdown
gitfault report          # write a self-contained interactive HTML report
gitfault wrapped         # a shareable "year in review" recap of the repo
gitfault guard <files>   # warn when a commit touches a fault-line file

Point it at any repo — no checkout needed

Pass a URL or a owner/repo GitHub shorthand and gitfault clones it into a temp dir, analyses it, and cleans up after itself:

gitfault -C pallets/flask              # owner/repo shorthand
gitfault hotspots -C facebook/react    # any subcommand works
gitfault -C https://github.com/django/django

Great for a 10-second "let's see the fault lines in that project" without leaving your terminal.

Curious what it says about projects you know? See the gallery — real health scores and hotspots for Flask, requests, Click, Express, fzf and bat, each reproducible in one command.

Markdown report

gitfault markdown prints the full analysis as GitHub-flavoured Markdown — tables render inline in issues, PRs and READMEs, so it's the most shareable output. Pipe it into a file, paste it into an issue, or commit it as a living HEALTH.md:

gitfault markdown                 # -> stdout (pipe or paste anywhere)
gitfault markdown -o HEALTH.md    # write to a file
gitfault markdown | pbcopy        # straight to the clipboard (macOS)

HTML report

gitfault report writes a single, self-contained .html file — hotspot treemap (files sized by lines, coloured by change frequency), plus the hotspot / coupling / knowledge tables — with no CDN, no tracking, and no network access. Open it locally, drop it in a CI artifact, or publish it to GitHub Pages.

(above: gitfault report run on pallets/flask — each tile is a file, sized by lines and coloured by how often it changes.)

gitfault report                       # -> gitfault-report.html
gitfault report -o docs/health.html   # choose the path
gitfault report --open                # write and open in your browser

Point it anywhere and scope it to a window:

gitfault hotspots -C ~/code/django --since "18 months ago" --top 15
gitfault coupling --include "src/**" --min-shared 6
gitfault knowledge --json | jq .bus_factor

gitfault wrapped — your repo's year in review

gitfault wrapped turns the same git history into a fun, screenshot-ready recap: commits, active days, your longest streak, the busiest month, night-owl share, top contributors and the single biggest commit of the year. It prints a colourful terminal card and can emit a self-contained SVG you can drop straight into a README or share anywhere.

gitfault wrapped                       # recap the latest year with commits
gitfault wrapped --year 2024           # a specific calendar year
gitfault wrapped --all-time            # the whole history
gitfault wrapped -C pallets/click --svg click.svg   # write a shareable card

The SVG needs no fonts, no CDN and no network — it reads only git log, so it works offline on any repo (yours, a client's, or owner/repo shorthand).

Keep the card fresh in your README (self-updating, no server)

Drop examples/gitfault-wrapped-card.yml into .github/workflows/ in your own repo. On a weekly schedule it regenerates the card and commits it to .github/gitfault-wrapped.svg, so this in your README stays up to date on its own — no hosting, no API keys, no external service:

![this repo, wrapped](https://raw.githubusercontent.com/OWNER/REPO/main/.github/gitfault-wrapped.svg)

gitfault guard — a pre-commit fault-line warning

gitfault guard checks the files you're about to commit and warns when one of them is a hotspot (churned often & large) or a knowledge silo (owned by a single person) — surfacing gitfault's core signal at the exact moment it matters, so you can pair up, add a test, or just review with extra care.

gitfault guard src/app.py            # check specific files
gitfault guard --strict src/app.py   # non-zero exit if any file is on a fault line

It's built to run as a pre-commit hook. Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/kenji-rasmussen/gitfault
    rev: v0.8.0
    hooks:
      - id: gitfault-guard

By default the hook is advisory (it prints but never blocks your commit). Pass args: [--strict] in the hook config if you'd rather fail the commit and force a conscious override.

Code-health badge

gitfault badge distils the whole analysis into a single 0–100 health score and prints a shields.io endpoint JSON. Commit that JSON anywhere it's reachable over HTTPS (a repo file, a gist, GitHub Pages) and shields renders a live badge you can drop in your README:

gitfault badge                          # -> {"schemaVersion":1,"label":"code health",...}
gitfault badge -o .github/badge.json    # commit this file
gitfault badge --label "codebase" -C pallets/click

![code health](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/.github/badge.json)

The score starts at 100 and subtracts penalties for git-derived risk signals. Change concentration — how much churn piles into the 10 biggest hotspots (up to −30) — always applies. Knowledge-silo penalties — the share of lines only one author has ever touched (up to −45) and a bus factor of 1–2 (−25 / −10) — apply only once a project has two or more contributors. A solo project is solo by definition, so "bus factor 1" there is nothing you can act on; penalising it would just brand every healthy small codebase with a scary grade. Grades: A ≥ 85, B ≥ 70, C ≥ 55, D ≥ 40, E ≥ 25, else F. A ready-to-copy workflow (examples/gitfault-badge.yml) regenerates and commits the badge on every push, so it stays current automatically.

What the numbers mean

Hotspot risk = change frequency × file size, each normalised. A tiny file edited 500 times isn't scary; a 3,000-line file edited 500 times is where your weekends go. The bar is relative to the worst offender in the repo.

Coupling degree = shared commits ÷ revisions of the less-active file. At 80% coupling, four out of five times you touch A you also touch B — that's a design seam worth knowing about (and often worth removing). Mega-commits (mass reformat/import) are excluded so they don't manufacture fake coupling.

Bus factor = the number of developers who together own at least half the lines currently in the repo. A bus factor of 1–2 on a large codebase is a real operational risk.

Options

By default gitfault ignores lockfiles, vendor/, node_modules/, dist/, minified assets, and common generated files so they don't drown the signal.

GitHub Action — hotspots on every PR

gitfault ships a composite Action (on the GitHub Marketplace) that posts a sticky comment on your pull requests with the current hotspots, change-coupling and bus-factor risk (and writes the same report to the job summary). Drop this in .github/workflows/gitfault.yml:

name: gitfault
on: pull_request
permissions:
  contents: read
  pull-requests: write   # needed to post the comment
jobs:
  gitfault:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # gitfault needs full history, not a shallow clone
      - uses: kenji-rasmussen/gitfault@v1
        with:
          since: "12 months ago"
          top: "10"

The comment is updated in place on each new push, so a PR never accumulates a pile of stale reports.

Why this exists

The idea — treating version-control history as behavioural data about a codebase — comes from the "behavioural code analysis" work popularised by Adam Tornhill (Your Code as a Crime Scene) and the commercial CodeScene product. The insights are genuinely useful, but the good tooling is proprietary and the original open tool (code-maat) is awkward to run. gitfault is a fast, zero-config, nicely-rendered CLI that gives you the core insights on any repo with a single command.

Roadmap

• ✅ GitHub Action that comments hotspots/coupling on pull requests (shipped — see above)
• ✅ Embeddable code-health badge (gitfault badge) (shipped — see above)
• ✅ Shareable "year in review" recap (gitfault wrapped) (shipped — see above)
• ✅ pre-commit hook that warns on fault-line files (gitfault guard) (shipped — see above)
• Complexity-weighted hotspots (indentation as a cheap complexity proxy)
• Trend mode: compare two time windows to see risk moving over time

Ideas and issues welcome.

License

MIT © Kenji Rasmussen