How can an auto-formatting Git pre-commit hook commit changes the developer never staged?

## The two views of a file Git has three states for content: the working tree (files on disk), the index (the staged snapshot that `git commit` turns into a tree), and `HEAD` (the last commit). `git add -p` exists precisely so you can stage some hunks of a file and leave the rest — the index copy and the disk copy of that path then legitimately differ. A hook script does not receive the index content. It runs with the working tree checked out and reads files with ordinary file I/O, so it sees the disk copy: staged hunks *plus* unstaged hunks *plus* anything else you were mid-way through editing. ## How the bug happens 1. You edit `payment.ts` in two places: a bug fix and an unrelated experiment. 2. You stage only the fix with `git add -p`. 3. You run `git commit`. The `pre-commit` hook fires. 4. The hook runs a formatter over `payment.ts`. The formatter reads the disk copy — the fix *and* the experiment — normalises whitespace and writes the whole file back. 5. The hook runs `git add payment.ts` so the formatting lands in the commit. 6. That `git add` stages the *entire* file, experiment included. The commit you thought contained one fix now also contains half-finished work. Nothing errored, nothing warned. This is a genuinely nasty failure because it damages exactly the developers doing the careful thing — the ones splitting work into reviewable commits. The same class of bug bites check-only hooks in the other direction: the hook validates disk content and passes, while the committed index content is different and would have failed. Your hook then gives a green answer about code that is not being committed. ## The mitigation staged-file runners implement A staged-file runner such as lint-staged handles this by isolating the working tree before running any command: it puts the unstaged portion aside, leaves only the staged content on disk, runs the configured commands against that, re-stages whatever they modified, and then restores the unstaged portion on top. Because it manipulates real state, an interrupted run is the one situation where you want to know how to recover — which is why these tools keep the removed work retrievable rather than deleting it. By hand, the equivalent trick is: `git stash push --keep-index --include-untracked` `--keep-index` means "stash everything, but leave the index's content on disk", so what remains in the working tree is exactly what is about to be committed. Run the checks, then `git stash pop` to bring the rest back. Expect conflicts on pop if the checks rewrote the same lines the stashed hunks touched — that is the unavoidable cost of the approach, and it is a real reason to prefer check-only hooks. A third option avoids touching the working tree at all: materialise the staged content somewhere else and check that. `git checkout-index --all --prefix=/tmp/staged/` writes the index content into a separate directory, and `git show :path/to/file` prints the staged version of one file to stdout. Both read the index directly, so no stashing is needed — at the cost of tools that expect real project layout and config resolution. ## Design guidance - **Prefer checking to fixing in a hook.** A hook that only reports leaves the developer's staged/unstaged split untouched, and its worst failure is a rejected commit rather than a corrupted one. - **If you do auto-fix, use a runner that isolates unstaged content.** Do not hand-roll `format . && git add -A` in a shell hook; `git add -A` in a hook is the single most common way teams create this bug. - **Never stage paths the developer did not touch.** Re-stage only the specific files the command modified, not the whole tree. - **Remember the escape hatch and the gap.** A developer under pressure can bypass the hook, and someone who never ran the hook manager's install has no hook at all. Whatever the hook fixes, CI must still verify on the pushed commits — the hook is an ergonomics tool, not the guarantee.