Discarding Local Changes to a Single File in Git

Reverting a Single File to its Last Committed State

Git is a powerful version control system, but sometimes you need to undo changes to a specific file without affecting the rest of your project. This tutorial explains how to discard local modifications and restore a single file to the state it had in the last commit.

Understanding the Problem

Often, you might find yourself making edits to a file and then realizing you want to revert to the last saved version. A full git reset --hard would discard all uncommitted changes, which is often undesirable. The goal is to selectively revert a single file while preserving your work on other files.

The git checkout Command

The primary tool for accomplishing this is the git checkout command. While git checkout is often used for switching branches, it can also be used to restore individual files from specific commits or states.

The basic syntax to revert a single file to the last committed state (HEAD) is:

git checkout HEAD -- <file_path>

• HEAD refers to the most recent commit on the current branch.
• -- is a separator that tells Git to treat everything that follows as a file path, even if it might look like a branch name.
• <file_path> is the path to the file you want to revert. For example, src/main.py or README.md.

Example:

To revert my_file.txt to its last committed state, you would run:

git checkout HEAD -- my_file.txt

This command replaces the current contents of my_file.txt with the version stored in the HEAD commit. Any uncommitted changes you made to the file will be lost.

Using Shorthand for HEAD

For convenience, you can use @ as a shorthand for HEAD:

git checkout @ -- my_file.txt

This is functionally equivalent to the previous example. However, be aware that older versions of Git might not support this shorthand.

Restoring from a Specific Commit

You aren’t limited to reverting to the HEAD commit. You can restore a file from any commit in your history. The syntax is:

git checkout <commit_hash> -- <file_path>

Replace <commit_hash> with the SHA-1 hash of the commit you want to restore the file from. You can find commit hashes using git log.

Example:

To restore my_file.txt from a commit with the hash a1b2c3d4, you would run:

git checkout a1b2c3d4 -- my_file.txt

Using git restore (Git 2.23 and later)

Git 2.23 introduced the git restore command as a more modern alternative to git checkout for restoring files. The syntax is similar:

git restore HEAD <file_path>

To restore from a specific commit:

git restore -s <commit_hash> <file_path>

The -s flag specifies the source commit.

Example:

To restore my_file.txt to the version in HEAD using git restore:

git restore HEAD my_file.txt

Important Considerations

• Uncommitted Changes are Lost: These commands will overwrite any uncommitted changes you’ve made to the file. Be sure to either commit or stash your changes before reverting if you want to preserve them.
• Staging Area: These commands also update the staging area (index) to match the restored file. This means the file will be marked as unchanged in Git.
• Safety: Always double-check the file path and commit hash before running these commands to avoid accidentally reverting the wrong file or restoring an outdated version.