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.

Pattern 1: Verify a Commit Series After the Fact

Whenever a commit series is claimed finished, verify it — don't trust that the hook (if any) already did, unless you've confirmed it isolates (Pattern 2). Two techniques, in order of preference:

A. Isolated worktree replay (most reliable, works for any range):

git worktree add --detach /tmp/verify-wt <first-sha>
cd /tmp/verify-wt
for sha in <sha1> <sha2> <sha3> ...; do
  git checkout --quiet "$sha"
  <build-command>   # e.g. cargo check --workspace --all-targets, go build ./..., npm run build
  <test-command>    # if fast enough to run per commit
done
cd - && git worktree remove --force /tmp/verify-wt

Report the actual pass/fail per commit — don't summarize as "all good" without having run this. If some commits fail in isolation, say so plainly; whether that's acceptable depends on whether the series needs to be bisectable (ask, don't assume).

B. git rebase --exec (fast, but stops at the first failure and needs a willingness to rewrite history to fix):

git rebase -i --exec '<build-command> && <test-command>' <base-sha>

Good for enforcing the guarantee going forward once every commit is fixed up; less good for a first-pass audit since it halts at the first broken commit rather than reporting the full picture.

Neither technique is language-specific — substitute whatever the project's real build/lint/test invocation is.

Pattern 2: Designing a Pre-Commit Hook That Checks the Commit

If a project wants a hook to enforce "every commit builds," the hook must put the working tree into the state the commit will actually produce before running anything that reads the filesystem. There are two categories of gate:

Index-native checks — no isolation needed. These read staged blobs directly and are naturally correct regardless of what else is unstaged:

• git diff --cached (content/whitespace/conflict-marker scans)
• git grep --cached (pattern scans across staged content)
• git cat-file -s :<path> (staged blob size)
• git diff --cached --name-only (which files are actually part of this commit)

Filesystem-native checks — need isolation. Anything that shells out to a real toolchain has no concept of "staged": cargo/go/pytest/tsc/ eslint/rubocop/golangci-lint/semgrep, and any full-codebase grep over the source tree rather than over git grep --cached.

The isolation algorithm (verified against a reproducible bug in the naive alternative — see Anti-Pattern below):

1. Diff the index against the working tree for tracked files: git diff-index --binary -r --no-color <tree-from-git-write-tree>.
2. Save that diff as a patch file; reset the differing tracked paths to the index's content: git checkout-index -f -- <paths-from-diff-index-name-only>.
3. Move untracked files to a temp directory (git ls-files --others --exclude-standard for the list).
4. Run every filesystem-native gate now — the working tree exactly matches what the commit will record.
5. Restore unconditionally on exit (trap ... EXIT, not just at the happy path's end): git apply the saved patch back, move untracked files back, clean up temp files.

This works identically regardless of language — the isolation step operates on git plumbing, not on the project's build tool.

Design checklist for the rest of the hook, independent of language:

• One gate that can never be skipped (secrets/credential scanning). Every other gate may have a documented, explicit skip mechanism, but skipping must never be silent or the default.
• Fast, index-native checks first; slow, filesystem-native checks (build, full test suite, SAST) last, so a trivial mistake fails in milliseconds rather than after a multi-minute compile.
• A toolchain/marker that's absent should report skipped, not failed and not silently passed — so the hook works on day one of a project and grows as new tech stacks are added, without needing a rewrite.
• If the project also has CI, treat the hook as the fast local signal and CI as the authoritative one — CI running per-commit (a matrix job over the commit range, or git rebase --exec in a CI step) is the only mechanism that catches history-construction mistakes a local hook's working-tree isolation might still miss (e.g. isolation itself disabled via an escape hatch, or the hook not installed on a contributor's machine). See the ci-cd skill for wiring that up.

Pattern 3: Splitting an Already-Finished Diff Into Logical Commits

When a large, complete change needs to become a readable series of commits (rather than one large commit):

1. Group by concern, not by file count. Read enough of each file's diff to know what it's actually doing before assigning it to a group — a file touched by three different concerns should go with whichever concern dominates its diff, and the commit message should say so honestly rather than implying the commit is narrower than it is.
2. Stage and commit incrementally, writing a substantial message per commit that explains what and why, matching the project's established commit-message conventions.
3. Verify with Pattern 1 before calling the series done. Do not assume intermediate commits build just because the final state does, and do not assume a passing hook proves it either unless you've confirmed the hook isolates (Pattern 2). If intermediate commits don't build in isolation, surface that explicitly and let the user decide whether it matters for their use case (no CI / no bisecting need vs. a project that relies on git bisect).
4. Prefer fixing forward over hiding the gap. If a commit needs to be independently buildable, the fix is usually moving a small piece (a struct field, an enum variant) earlier via interactive rebase — not disabling the hook or skipping verification.

Anti-Patterns

• git commit --no-verify to skip a hook that's "probably fine to skip this once." If a hook is wrong, fix the hook; if it's right, don't bypass it.
• git stash --keep-index --include-untracked as an isolation mechanism. Reproducible bug (confirmed on git 2.43): when a tracked file has both a staged change and a further unstaged edit on top of it — ordinary partial staging — popping the stash produces a spurious merge conflict, even though the two changes don't overlap. This is the exact scenario the isolation exists to support, so the failure mode defeats the purpose. Use the diff/patch approach in Pattern 2 instead; it never invokes a 3-way merge, so it has no conflict surface.
• Treating "the hook passed" as proof of per-commit integrity without having checked whether the hook isolates the working tree at all. Most hand-written hooks don't, until someone goes looking.
• Assuming a big refactor's intermediate commits are fine because the final commit compiles. They are two different claims; only verify the one you're actually about to assert.