git restore: Usage, Options & Common CI Errors

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.

Related guides

git reset: Usage, Options & Common CI Errorsgit reset moves HEAD and optionally the index and working tree. Reference for --soft, --mixed, --hard, and ho… git checkout: Usage, Options & Common CI Errorsgit checkout switches branches and restores files. Reference for -b, --detach, and pathspecs, plus the detach… git clean: Usage, Options & Common CI Errorsgit clean removes untracked files from the working tree. Reference for -n, -f, -d, -x, and the "would clobber… git status: Usage, Options & Common CI Errorsgit status shows staged, unstaged, and untracked changes plus branch state. Reference for -s, --porcelain, -b…