git restore: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

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

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

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.

- 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