# git restore --staged: Unstage Files & CI Errors

> git restore --staged unstages files without touching the working tree, the modern replacement for git reset HEAD. Reference for usage, scope, and gotchas.

Source: https://latchkey.dev/learn/command-reference/git-restore-staged  
Updated: 2026-06-25

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

```Terminal
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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git restore --staged: Unstage Files & CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt