Correction, same day: the original version of this record used
git stash push -- <pathspec>to isolate the file. In practice,git stash show --name-onlyon that stash entry listed all 14 changed files, not just the one pathspec target. Root cause, confirmed by the observed behavior below:git stash pushalways creates a full snapshot commit of the entire index and working tree at the moment it runs — the pathspec argument only controls which paths get reverted from the working directory and index afterward, it does not filter what gets recorded into the stash object. Popping that stash later, after the other 8 files had already been committed to the source branch, risked git trying to reapply already-identical changes on top of them — a needless conflict surface. The procedure below replaces the stash step withgit restore --staged, which touches only the specified path's index entry and carries no such risk.
On feat/letters-logdistributionevent, working-tree changes had accumulated across two unrelated efforts:
docs/subsystems/person/PL-3-person-to-person-link-spec.md — a spec for unrelated person-to-person linking work that belongs on a branch that doesn't exist yet: feat/person-person-personlinks.git add . had already been run twice, so by the time this was addressed, the new file was sitting in the index as an A alongside the eight M entries. Goal: split the new file out, commit the rest to the current branch, then carry the new file over to a fresh branch as its first commit.
# 1. Unstage ONLY the new spec file — its index entry is reset to HEAD (nonexistent),
# leaving every other staged file's index entry untouched
git restore --staged docs/subsystems/person/PL-3-person-to-person-link-spec.md
# 2. Verify the split — see footnote [^verify]
git status --short
# 3. Commit everything else to the current branch
git commit -m "your commit message"
# 4. Create and switch to the new branch — untracked files travel with checkout
# by default; see footnote [^checkoutcarry]
git checkout -b feat/person-person-personlinks
# 5. Confirm the file made the trip
git status --short
# 6. Stage and commit it there
git add docs/subsystems/person/PL-3-person-to-person-link-spec.md
git commit -m "Add PL-3 person-to-person link spec"
After step 1's git status --short, the eight M entries remain staged (M in the first column), and PL-3 moves from staged (A ) to the "Untracked files" section — not gone, not deleted, just unstaged.[1]
After step 3, git log -1 --stat on the current branch shows the 8-file commit; PL-3 should not appear in it.
After step 4's checkout, step 5's git status --short should show exactly one line:
?? docs/subsystems/person/PL-3-person-to-person-link-spec.md
If anything else appears, or the file is missing entirely, stop before committing — something in the working tree state diverged from what this procedure assumes.[2]
The file moves to "untracked" rather than showing as a pending deletion because git restore --staged resets the given path's index entry to match HEAD. Since HEAD never tracked this file, its HEAD state is "does not exist," so the index entry for it is simply removed — leaving the file exactly as it was on disk, just no longer staged. ↩︎
The realistic failure mode here is a typo in the path or running the commands from the wrong working directory — not any interaction between git restore and the other staged files, since git restore --staged <path> is scoped to that single index entry by construction. If step 2 shows the wrong file affected, git add it back and re-run step 1 with the corrected path. ↩︎