How to restore a deleted file

Where a deleted file went, and how to get it back, depends on the step at which it vanished. Three cases, from the easy one to the hard one: the delete is still in the working directory, the delete is already in a commit, or the commit that held the file was wiped by reset --hard. Start with the one closest to your situation.

The file is gone but the last commit is intact

You removed the file in the working directory and have not run git rm or committed yet. The version from the last commit is still there.

$ rm report.txt
$ git status --short
 D report.txt

A lone D in the second column means "the file is missing from the working directory, but git still knows it". git restore brings it back:

$ git restore report.txt

No prompt, no output; the file is on disk again and git status is clean. The default source here is the index, which matches the last commit because you staged nothing.

The delete is already committed

The file was removed with git rm and the delete went into a commit, so the top of git log is the deletion and the file itself is no longer in it.

$ git log --oneline
7c2f9a3 removed the report draft
2b90f14 added the hiring section
00ef0ff first draft of the report

The file is alive in the previous commit. Pull its version out with --source:

$ git restore --source=HEAD~1 report.txt
$ git status --short
?? report.txt

The file is back on disk, but git treats it as new: restore without --staged touches the working directory only. git add report.txt and a commit record it in the history again. The older spelling uses git checkout: git checkout HEAD~1 -- report.txt pulls the file out and stages it in one step. Instead of HEAD~1 you can name the hash of any commit where the file still existed: git checkout 2b90f14 -- report.txt.

reset --hard wiped the commit that held the file

The worst case is a file that lived in a commit, where the commit itself dropped out of the history after git reset --hard. git log no longer shows it, but the hash is still in git reflog:

$ git reflog
024f79c HEAD@{0}: reset: moving to HEAD~1
ef4b778 HEAD@{1}: commit: put report.txt back
024f79c HEAD@{2}: commit: edits to the intro

HEAD@{1} is the dropped commit. Take the file out of it by hash:

$ git restore --source=ef4b778 report.txt

This does not move the branch: you take one file out of the lost commit, not the whole history back. If you want the entire commit, that is git reset --hard ef4b778, but the file is usually enough.

Common mistakes

A file that never made it into a commit has nothing to restore from. Run git restore --source=HEAD~1 notes.txt on such a file and git answers error: pathspec 'notes.txt' did not match any file(s) known to git. Git keeps only what it has seen at least once: check the name, and check that the file was ever committed.

The second trap is easy to miss: git restore --source writes the file into the working directory, not the index. After it, git status shows the file as untracked, and until you run git add it will not go into the next commit. "On disk" and "in the history" are two different states.

Where this is in the book

Undoing level by level is in chapter 4; rescuing work through the reflog is in chapter 8.

Chapter 4. Inspect, undo, ignore

Chapter 8. First aid: when something goes wrong