Git restore copies selected tracked paths from a chosen source into the working tree, the index, or both. It can undo unwanted edits or recover a file from another tree, but it can also discard local changes. The key question is not simply which command to run; it is which state should be copied into which destination.
This guide explains source defaults, staging, path scope, and recovery so a targeted file operation does not become accidental loss of work. Review the repository state before every destructive restoration.
Distinguish HEAD, index, and working tree
HEAD identifies the current checked-out commit, the index holds the staged snapshot for the next commit, and the working tree contains the files being edited. These states can all differ at the same path.
Use git status and appropriate staged and unstaged diffs to understand the difference. A file marked modified does not tell you whether useful changes exist in one destination or both.
Decide which state should remain authoritative. Restoring the working tree from the index can preserve staged work while discarding later edits. Restoring the index from a commit changes what will be committed without necessarily removing working-tree edits.
Choose the destination explicitly
The worktree and staged options select different destinations under Git’s documented rules. Combining them can update both. Do not assume a command that unstages changes also erases them from the working tree.
State the intended outcome before acting: unstage the file, discard an unstaged edit, or replace both states with content from a chosen commit. These are different operations even when the path is identical.
Check the exact supported syntax for your Git version. A copied command with broad destination options can discard more state than a narrow recovery requires. Prefer the smallest path and destination scope that meets the goal.
Understand source defaults
Without an explicit source, Git’s default source depends on the destination options. Working-tree restoration normally draws from the index, while staged restoration uses the documented commit default. Review that distinction before relying on a short command.
Use an explicit source when the intended content comes from a particular commit or branch. Record its commit identity so the result is reproducible. A branch name can move after the recovery is discussed.
If a tracked path does not exist in the selected source, restoration can remove it to match that source. Do not describe restore as an unconditional file-recovery command that can never delete a path.
Preserve valuable uncommitted work
Before discarding edits, save work through an appropriate commit, stash, patch, or protected copy. Choose a method that covers the files actually involved. Untracked files and ignored artifacts have their own preservation behavior.
Do not assume reflog can reconstruct every uncommitted edit. It records relevant reference movements, not a universal history of arbitrary working-tree content. Preservation must happen before destructive replacement where possible.
Review the backup or saved diff enough to confirm it contains what matters. A preservation command succeeding does not prove the intended files were included. Recovery should not depend on an untested assumption about scope.
Keep path selection narrow
Use explicit paths and the pathspec separator where appropriate. A broad pathspec can affect many files, and shell expansion can change what Git receives. Quote paths according to the shell and supported pathspec behavior.
For large path lists, use the documented file-based pathspec options where appropriate. Handle names with spaces or unusual characters correctly. A newline-separated convenience file may not represent every filename safely.
Preview repository state and compare selected paths before applying a bulk operation. Git restore does not provide a universal dry-run safety net for every workflow. Narrow scope and preserved state are more dependable than a guessed preview flag.
Use patch mode for deliberate partial changes
Patch selection can restore selected portions rather than a whole file. It is useful when one edit is unwanted but another should remain. Inspect each chosen hunk instead of accepting every prompt mechanically.
A hunk is a textual unit, not necessarily a complete semantic change. Removing one section can leave an import, test, or related call inconsistent. Review the resulting full file and dependent behavior.
Confirm whether patch mode applies to the intended destination and source. Interactive convenience does not remove the need to understand what snapshot is being modified.
Handle conflicts through the active operation
During a merge or rebase, the index can contain unmerged stages. Relevant restore options have documented restrictions and meanings in that state. Do not apply a normal clean-index example without checking the ongoing operation.
The labels ours and theirs can be especially confusing across merge and rebase workflows. Read the operation’s documented interpretation and inspect content before selecting a side. Names alone are not a correctness decision.
After restoration, verify conflict state and the complete resolution. A file without markers can still be wrong or remain unmerged in the index. Use status, diffs, and tests together.
Verify before creating the next commit
Inspect staged and unstaged diffs after the command. Confirm only intended paths and destinations changed. A successful restore proves Git performed the operation, not that the chosen source was correct.
Run relevant tests when restoring code or configuration from an older tree. The recovered file may depend on interfaces that no longer exist in the current branch. Historical validity does not establish present compatibility.
Do not commit merely because the index is now tidy. The intended commit should still represent one reviewed change and preserve unrelated work. File restoration is a step inside the workflow, not its approval.
Choose revert when history is the target
Restore changes file state; it is not the same as recording an inverse commit for an already published change. If shared history needs a corrective change, review whether git revert fits the team’s policy.
Avoid replacing files from an old tree and assuming that undoes every effect of a published commit. Renames, deletions, configuration, and dependencies may be missed. Choose the mechanism from the intended history outcome.
For an accidental unstaged edit, preserve valuable work, restore only the affected path from the intended index state, and inspect the result. For a published regression, use the team’s reviewed corrective-history workflow instead.
Frequently asked questions
Does restoring staged state always erase working edits?
No. Destination options determine which state changes.
Can restore remove a tracked file?
Yes, when matching a source that lacks the path under the documented behavior.
Where are source defaults and conflict options explained?
Read the Git restore reference before choosing the exact operation.
For a complementary workflow, read Git Revert: Reverse a Change Without Erasing History.
