What you can do after this lesson
You will know the safe, modern commands for the three smallest undo jobs: throwing away edits, unstaging, and pulling an old version of a file back. Be aware of one fact that shapes all of this: Git can only protect what it has recorded. A change that is committed is very hard to lose. A change that is only in your working tree is not stored anywhere else, so discarding it is permanent.
git restore and git switch were introduced in Git 2.23 to split up the old, overloaded git checkout command. They work in the Git 2.55 we tested against, and the older checkout forms still exist.
Discarding edits in the working tree
You edited a tracked file and decided the edit was a mistake:
echo "juice" >> drinks.txt
git status -s
git restore drinks.txt
cat drinks.txt M drinks.txt
tea
coffeeThe file went back to the version in the staging area (or, if nothing was staged, the last commit). The edit is gone. There is no confirmation and no undo. Before discarding anything you might want, look at git diff drinks.txt one last time.
Unstaging a file
You ran git add on a file you did not mean to include in the next commit. Unstaging moves it back out of the staging area while leaving your edits in place:
echo "juice" >> drinks.txt
git add drinks.txt
git restore --staged drinks.txt
git status -s M drinks.txtThe status changed from staged (M in the left column) to modified but not staged ( M). Nothing was lost. Git's own status output reminds you of this command: after git add it suggests git rm --cached for a brand new repository, and git restore --staged otherwise.
Doing both at once
To drop a change from both areas, naming the source explicitly:
git restore --source=HEAD --staged --worktree drinks.txtThis resets both the staging area and the working file to the last commit. The same flags let you restore from other places.
Bringing back an old version of a file
--source accepts any commit, branch or tag. Suppose shopping.txt once held one line, and the file has grown since. Restore the old content into your working tree:
git restore --source=HEAD~2 shopping.txt
cat shopping.txt
git status -sbuy flour
M shopping.txtThe file now shows the old content and Git reports it as modified, because it differs from the latest commit. You can commit it (to make the old content current again) or restore it again to undo this. To look at the old version without changing anything, use git show HEAD~1:shopping.txt, which prints the file as it was in that commit.
Removing untracked files with git clean
git restore only works on tracked files. A new file that was never added is untracked, and git clean removes those. Always preview first:
echo scratch > junk.txt
git clean -nWould remove junk.txtgit clean -fRemoving junk.txt-n is the dry run; -f (force) is required to delete. Add -d to include untracked directories. Ignored files are left alone unless you add -x. Because untracked files were never recorded, git clean is unrecoverable.
A habit that makes undoing cheap
Because committed work is nearly always recoverable, the safest habit is to commit often, even roughly, on a branch you can tidy later. Another option is git stash (lesson 22) which stores uncommitted work out of the way without discarding it. When you are unsure whether you will want an edit back, stash or commit it instead of restoring over it.
Choosing the right command
| Situation | Command |
|---|---|
| Throw away edits to a file | git restore file |
| Take a file out of the next commit, keep the edits | git restore --staged file |
| Reset both the staged and working copy | git restore --source=HEAD --staged --worktree file |
| Get a file from an older commit | git restore --source=<commit> file |
| Remove a never-added file | git clean -n then git clean -f |
Looking before you leap
A short routine keeps these commands safe. Run git status to see what Git thinks is changed. Run git diff for the lines at stake. Ask yourself whether you might want any of it back. If the answer is maybe, make a quick commit on a scratch branch or use stash first, because a throwaway commit costs nothing and can be deleted later. Discarding is only safe once you are certain, and certainty is cheap to buy with one extra command.
Common mistakes
- Running
git restore .without reading the diff. The dot means every file under the current folder. - Expecting
git restoreto be undoable. Unrecorded edits cannot be recovered. - Using
git clean -fwithout-nfirst. You may delete files that mattered. - Confusing unstaging with discarding.
--stagedkeeps your edits; plainrestoreremoves them. - Restoring from the wrong commit. Check what
HEAD~2points to withgit log --onelinefirst.
Exercise
- In a repository with a committed
notes.txt, add a line and discard it withgit restore. - Add a line again, stage it, then unstage it and confirm the edit survives.
- Create an untracked file, preview its removal with
git clean -n, then remove it.
Show one possible answer
echo "extra" >> notes.txt
git restore notes.txt
echo "extra" >> notes.txt
git add notes.txt
git restore --staged notes.txt
cat notes.txt
echo temp > temp.txt
git clean -n
git clean -fAfter step 2, cat notes.txt still shows the extra line, and status reports M notes.txt.
Next: Fixing the last commit: amend and the three kinds of reset.
Key points
- git restore <file> discards working-tree changes and cannot be undone, because uncommitted edits are not stored anywhere.
- git restore --staged <file> unstages a file but keeps your edits.
- git restore --source=<commit> <file> brings back the version from any commit.
- git clean removes untracked files; use -n first to preview.
- Commit or stash work you might want back before you discard anything.