git restore --staged: Unstage Files & CI Errors

git restore --staged is the clear, modern way to unstage files while keeping your edits.

When you over-stage, restore --staged removes files from the index without discarding your working-tree changes.

What it does

git restore --staged copies content from HEAD into the index for the named paths, effectively unstaging them, while leaving the working-tree files exactly as they are.

Common usage

git restore --staged file.txt     # unstage one file
git restore --staged .            # unstage everything
# equivalent older form:
git reset HEAD file.txt
# unstage AND discard:
git restore --staged --worktree file.txt

Common errors in CI

error: pathspec did not match - the path is not staged or is mistyped. Remember --staged alone keeps your edits (only unstages); to also throw the edits away you must add --worktree. On a brand-new repo with no HEAD, unstaging needs git rm --cached instead.

Related guides