git apply

Lower-level than git am. No commit, no email parsing — just patch.

🎯 What & why

git apply consumes a unified diff and rewrites the working tree (and optionally the index) to match. It is the patch-engine half of git am — no mailbox parsing, no commit creation, just bytes-on-disk surgery.

🧠 Mental model

Pure working-tree (and optionally index) mutation. With --cached it touches only the index (staged blobs in the object DB + index entries); without it, files on disk change and the index is left alone unless --index is given. No refs move, no commit objects are created.

🛠️ Synopsis

git apply [--stat] [--numstat] [--summary] [--check] [--index | --cached]
          [-3 | --3way] [--whitespace=<action>] [-R | --reverse]
          [--reject] [-p<n>] [-C<n>] [--unidiff-zero] [--allow-empty]
          [--exclude=<pattern>] [--include=<pattern>] [<patch>...]

🎚️ Switches & options

Flag	What it does
`--check`	Dry-run: verify the patch would apply cleanly. Exits non-zero on failure.
`--stat / --summary`	Show a diffstat or rename/copy/mode summary instead of applying.
`--index`	Apply to BOTH the working tree and the index (the patch must apply to the current index).
`--cached`	Apply to the index ONLY; the working tree is untouched. Pairs well with bare or scripted flows.
`-3, --3way`	Fall back to a 3-way merge using blob OIDs in the patch when context fails. Requires those blobs in the object DB.
`-p<n>`	Strip <n> leading path components (default 1, like `patch -p1`). Use `-p0` for paths with no a/ b/ prefix.
`-C<n>`	Require <n> lines of matching context (default 3). Lower it to force-fit fuzzy patches.
`--whitespace=<action>`	How to handle whitespace errors: nowarn\|warn\|fix\|error\|error-all. `fix` rewrites trailing-WS lines.
`--reject`	⚠️ On failure, write `.rej` files for hunks that didn't apply. Leaves a partial mess — review every reject.
`-R, --reverse`	Apply the patch in reverse. Handy for unrolling a previously-applied diff.

💡 Use cases

Test a patch from a mailing list or PR before committing: git apply --check foo.patch.
Stage a diff produced elsewhere directly into the index without touching the worktree: git apply --cached foo.patch.
Re-apply a reverted change: git apply -R old.patch to undo, then re-apply later.
Pipe a generated diff straight into the repo without temp files: diff -u a b | git apply -p0.

🧪 Examples

Validate before applying

git apply --check 0001-fix.patch

Apply to index and worktree

git apply --index 0001-fix.patch

3-way fallback when context drifts

git apply -3 0001-fix.patch

Reverse-apply a hunk file

git apply -R bad-change.diff

🎓 Recommendations

Always run --check first on patches from untrusted sources — failures are silent corruption otherwise.
Prefer git am when the patch carries author/message metadata; reach for git apply only when you have a raw diff.
Use -3 whenever the patch was generated against a known commit that exists locally — much friendlier than --reject.

🪤 Common pitfalls

Without --index or --cached, the index is NOT updated — your worktree and index will disagree until you git add.
--reject leaves .rej and partially-modified files behind; forgetting to clean up before committing ships broken hunks.
Whitespace settings from core.whitespace and apply.whitespace silently change behavior — patches that 'just worked' yesterday can fail after a config change.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.