| name | git-conventions |
| description | Use when running git commands that touch a subset of changes — git stash push with a pathspec while the index has staged-added (new) files, or generating/applying patches that include binary files. Prevents stashes that silently capture every staged-add and binary patches that fail to apply. |
| user-invocable | false |
git stash push -- <pathspec> Captures All Staged-Adds
git stash push -m "msg" -- <paths> filters tracked-modified files ( M) by the pathspec correctly, but unconditionally captures every staged-added file (A , AM) in the index regardless of the pathspec. A stash you intended to hold 12 files becomes those 12 plus every staged-add in the working tree, and popping it re-applies those staged-adds — a clean no-op if their content is unchanged, but an add/add conflict if it has since diverged.
When the index contains staged-adds and you need to stash only a subset, don't trust git stash push -- <paths>. Use one of:
- Sidestep (simplest): commit everything to a temp commit, then
git reset --mixed HEAD~1 so the staged-adds become untracked files — which git stash push -- <paths> leaves alone unless you pass -u — then stash the tracked-modified subset cleanly.
- Plumbing rebuild when you can't disturb the index:
cp .git/index .git/index.bakgit read-tree HEAD (reset index to HEAD)git add -- <paths> (stage just the subset)TREE=$(git write-tree); PARENT=$(git rev-parse HEAD)INDEX=$(echo "index on $branch: msg" | git commit-tree $TREE -p $PARENT)WIP=$(echo "On $branch: msg" | git commit-tree $TREE -p $PARENT -p $INDEX)git update-ref -m "On $branch: msg" --create-reflog refs/stash $WIP — the -m is required; a positional message is parsed as old_value and errors with "not a valid old SHA1".mv .git/index.bak .git/indexgit checkout HEAD -- <paths> to revert the subset in the working tree.
Binary Patches Need --binary
When generating a patch that includes binary files (images, fonts, compiled assets), use git diff --binary. A plain git diff patch fails to apply with cannot apply binary patch to '<file>' without full index line.
