git-commit-integrity

Git Commit Integrity

Purpose

A commit records a tree snapshot. Nothing about git commit — or a hook that runs during it — guarantees that snapshot builds, lints, or tests cleanly on its own. The only thing most tooling actually checks is "does the working directory look okay right now", and those two questions are the same only in the ordinary one-change-at-a-time workflow. They diverge the moment more than one commit's worth of work exists in the working tree at once — which is exactly the situation whenever a large, already-finished diff is being organized into multiple readable commits after the fact.

This skill exists because that divergence is easy to miss: every gate can report green and the resulting history can still contain commits that don't build if checked out alone.

When to Invoke

• Splitting a large, already-complete diff into multiple logical commits (a refactor, a big feature, an after-the-fact history cleanup).
• Writing or reviewing a pre-commit / pre-push hook, in any language.
• A user or reviewer asks "is this commit series bisectable?" or "does each commit build?"
• Before claiming a multi-commit series is clean, complete, or ready for review — verify it, don't infer it from "the hook passed."

Core Principle: A Commit Is Its Snapshot, Not Your Working Directory

Compilers, linters, and test runners (cargo, go build, pytest, tsc, eslint, rspec, ...) read the filesystem. None of them know git's index exists. A tool invoked mid-commit checks whatever is on disk at that moment — staged changes, unstaged changes, and untracked files, all mixed together indiscriminately. git status/git diff --cached can tell you what will be committed; it takes a deliberate extra step to make what a tool checks match that.

Two consequences follow directly:

1. A passing hook is not proof a commit is buildable in isolation unless you know the hook isolates the working tree to the index before running anything filesystem-based. Most hand-written hooks don't, because it isn't obvious the gap exists until you go looking for it.
2. Splitting a finished diff into several commits by staging subsets is not, by itself, a safe operation. Each intermediate commit's actual recorded tree may reference symbols, fields, or files that don't exist yet at that point in history, even though the ambient working directory (with later batches still sitting unstaged) compiles fine.