# git restore: Usage, Options & Common CI Errors

> git restore discards working-tree changes or unstages files. Reference for --staged, --source, --worktree, and how it differs from the older git checkout.

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

git restore is the modern, focused way to discard changes or unstage files.

git restore splits the file-restoring half of the old git checkout into a clearer command.

## What it does

git restore updates files in the working tree (and/or the index with --staged) from a source, defaulting to HEAD. It does not move branches.

## Common usage

```Terminal
git restore file.txt          # discard working-tree changes
git restore --staged file.txt # unstage, keep working changes
git restore .                 # discard all working-tree changes
git restore --source=HEAD~2 file.txt
```

## Options

| Flag | What it does |
| --- | --- |
| --staged / -S | Restore the index (unstage) |
| --worktree / -W | Restore the working tree (default) |
| --source=<tree> / -s | Restore content from a commit/tree |
| --ours / --theirs | Pick a side during a conflict |

## Common errors in CI

error: pathspec 'X' did not match any file(s) known to git - the path is not tracked or is misspelled. To both unstage and discard, run git restore --staged --worktree <file>. Restoring discards uncommitted work permanently, so it is intentionally destructive.

## 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: Usage, Options & Common CI Errors?

git restore splits the file-restoring half of the old git checkout into a clearer command.

### What it does?

git restore updates files in the working tree (and/or the index with --staged) from a source, defaulting to HEAD. It does not move branches.

### Common errors in CI?

error: pathspec 'X' did not match any file(s) known to git - the path is not tracked or is misspelled. To both unstage and discard, run git restore --staged --worktree <file>. Restoring discards uncommitted work permanently, so it is intentionally destructive.

---

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