Git Restore: Recover a File from the Right Source

You edit a file, stage some changes, then edit it again. To discard the latest experiment, the important question is not just which command to run, but which version to recover. Git restore lets you choose a source and destination; confusing them can discard unsaved work.

1. Identify three versions first

This guide assumes a repository with an existing commit, a tracked file and no active merge conflict. Suppose src/Example.php has version A in HEAD, version B in the index after git add, and version C in the working tree after further edits.

• HEAD: content from the current commit.
• Index, or staging area: content prepared for the next commit.
• Working tree: the file currently in your working directory.

B and C need not be identical just because they share a filename. An earlier add does not automatically stage later edits.

2. Read status and diffs first

git status --short
git diff -- src/Example.php
git diff --cached -- src/Example.php

In the A–B–C scenario, the first diff compares B with C; the cached diff compares A with B. These inspection commands do not restore or delete file content.

Replace the example path with your actual file. Before using a write command below, independently back up everything you still need, including the staged version if you need it separately. A working-tree copy preserves C, not a separate copy of B. Confirm that your backup is readable before proceeding.

3. Select the source and destination

The Git restore documentation specifies that the default source is the index, or HEAD when --staged is used. This table assumes the file exists in all three locations. Each row starts independently from A–B–C.

Warning: the first and third rows overwrite the working tree and can discard uncommitted edits. The second preserves the working file but replaces index content. These are alternatives, not three commands to execute in sequence.

The -- separator distinguishes options from paths. While learning, select one explicit file; do not broaden the command to a dot or a whole-directory pattern for convenience.

4. Match the choice to your intention

If B is reviewed work and C is an unwanted experiment, restoring the index version into the working tree may fit after backing up. If you only want to unstage changes to reorganize a commit, use --staged and retain C for further work.

To inspect the current committed content, first read it with git show HEAD:src/Example.php; overwriting the file is unnecessary. Choose --source=HEAD --worktree only when you genuinely want the working file to become A and accept replacing its current contents.

5. Verify the result and understand the limits

Run status and both diffs again, read the file and run relevant tests. A successful restore command proves neither that you selected the intended version nor that the resulting code is correct.

If a tracked path is absent from the restore source, restore can remove it to match that source. A new file never recorded by Git has no version waiting in HEAD. Do not treat reflog as a guaranteed backup for uncommitted content.

The practical rule is to identify the source, identify the destination, preserve needed work, then restore one explicit path. Git restore is most useful when you know which version it will replace.