Undoing Uncommitted Changes with Git Restore

Previously in this course, we covered how to define patterns for files Git should ignore in Ignoring Files: Mastering .gitignore for Cleaner Repositories. Now that your repository is shielded from junk files, this lesson focuses on how to manage the "mess" that happens within your tracked files: accidental changes you aren't ready to save.

Understanding the "Dirty" Working Directory

In Understanding the Git Lifecycle: Staging Area & Working Directory, we established that your working directory is your "sandbox." It is where you edit code, test ideas, and occasionally break things.

Often, you’ll find yourself in a situation where you’ve modified a file, realized the direction is wrong, and simply want to "go back to how things were" before you committed or staged those changes. This is where git restore becomes your primary tool for cleanup.

The Power of git restore

Introduced in later versions of Git (2.23+), git restore was designed to replace the often-confusing dual-purpose behavior of git checkout. Its sole job is to restore files to a previous state—specifically, the state they were in at the last commit.

When you run git restore <filename>, Git looks at the version of that file in the HEAD commit (your last save) and overwrites the version in your working directory.

Important: This action is destructive. Once you run this command, the changes you made in your editor are gone. There is no "undo" for a git restore because Git cannot recover what it never tracked.

Worked Example: Discarding Local Changes

Let’s advance our project by simulating a common mistake. Suppose we are working on our project documentation.

1. Modify a file: Open your project’s README.md and add a line of nonsense text: This is a mistake.

2. Check the status: Run git status in your terminal. You will see the file listed under "Changes not staged for commit."

3. Revert the change: Since you haven't staged this file yet, you can discard these modifications instantly:

   Bash
   git restore README.md
   

4. Verify the restoration: Run git status again. The file should no longer appear as modified, and if you open README.md in your text editor, you’ll see the "mistake" line is gone.

Hands-on Exercise

To practice this, perform the following steps in your project folder:

1. Create a new file named temp_notes.txt.
2. Add some text to it and save the file.
3. Use git add temp_notes.txt to stage it.
4. Modify temp_notes.txt again by adding a new sentence after you staged it.
5. Run git status to see both the staged version and the unstaged modification.
6. Use git restore temp_notes.txt and check the status again. Note: You will notice the file remains "staged" but the second set of modifications is discarded.

Common Pitfalls

• Forgetting it's destructive: Always remember that git restore is a one-way street. If you have unsaved work in your IDE that you haven't committed, ensure you really want to lose it before running the command.
• Confusing it with git reset: While git restore operates on the working directory, git reset is a more powerful (and dangerous) tool used to move the commit pointer itself. If you're just cleaning up your current file, stick to git restore.
• Assuming it deletes new files: If you create a brand new file that Git has never seen before, git restore will not "remove" it, as there is no version in the commit history to restore to. For new, untracked files, you must use rm or your file explorer.

FAQ

Does git restore work on multiple files at once? Yes. You can provide a list of filenames (git restore file1.txt file2.txt) or even a directory to restore everything within it.

Can I restore files to a specific commit? Yes, by using the --source flag (e.g., git restore --source=HEAD~1 filename.txt), but for standard "undoing uncommitted changes," the default behavior is sufficient.

Is git restore safe for files I've already committed? Yes. It only affects the working directory version of the file, not the repository history.

Recap

We have learned how to maintain a clean working directory by discarding unwanted, uncommitted changes using git restore. This tool is your safety net, allowing you to experiment freely without worrying about permanently cluttering your project with trial-and-error code.

Up next: We will look at how to reverse the "staging" process using git restore --staged to pull files back out of the staging area without losing your work.