git restore --staged: Unstage Files & CI Errors

By Kaveh Alemi·Latchkey

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation