git restore --source: Usage, Options & Common CI Errors

git restore --source brings a file back from any commit without changing branches.

When you need one file as it existed at an earlier revision - not a full checkout - restore --source is the focused tool. It is the modern replacement for git checkout <rev> -- <path>.

What it does

git restore --source=<tree> copies the named paths from that commit or tree into the working tree (and the index too if --staged is added), without moving HEAD or any branch.

Common usage

Terminal

git restore --source=HEAD~2 file.txt
git restore -s main -- path/to/file
git restore --source=v1.0.0 --staged --worktree config.yml
git restore -s origin/main -- src/

Options

Flag	What it does
--source=<tree> / -s	Commit/tree to restore content from
--staged / -S	Also restore into the index
--worktree / -W	Restore the working tree (default)
-- <path>	Limit to specific paths

Common errors in CI

error: pathspec ‘X’ did not match any file(s) known to git - the path does not exist in that source revision, or the revision is absent on a shallow clone. Verify the path existed then (git ls-tree <rev>), and deepen history if the source commit was never fetched.

Related guides

git restore: Usage, Options & Common CI Errorsgit restore discards working-tree changes or unstages files. Reference for --staged, --source, --worktree, an… git restore --staged: Unstage Files & CI Errorsgit restore --staged unstages files without touching the working tree, the modern replacement for git reset H… git switch --detach: Usage, Options & Common CI Errorsgit switch --detach checks out a commit without attaching to a branch. Reference for detaching at a SHA or ta… git ls-tree: Usage, Options & Common CI Errorsgit ls-tree lists the contents of a tree object - files, modes, and ids. Reference for -r, --name-only, -l, a…