Introduction

Restoring a single file from an old commit is one of the safest ways to fix regressions without reverting an entire branch. Git provides commands for previewing historical content, applying full-file restore, or selectively restoring specific hunks. A clean workflow starts with inspection, then applies only the minimal needed change.

Core Sections

Inspect file history before restoring

Identify the exact commit that contains the desired version of the file.

git log --oneline -- path/to/file.py
git show <commit_sha>:path/to/file.py

Use full commit hash when possible to avoid restoring from the wrong revision.

Restore full file into working tree

With modern Git, git restore is the clearest way to bring one file from old commit into current branch working tree.

git restore --source <commit_sha> -- path/to/file.py
git status

This updates working tree file content but does not commit automatically. Review changes before staging.

Stage and commit restored file

After confirming diff, stage only that file and commit with clear message.

git diff -- path/to/file.py
git add path/to/file.py
git commit -m "Restore file.py from <commit_sha>"

Single-purpose commit messages help future debugging and blame analysis.

Restore only selected hunks

If you only need part of an old file, use interactive patch restore.

git restore -p --source <commit_sha> -- path/to/file.py

This is useful when old commit contains desired logic plus outdated unrelated edits.

Alternative command for older Git versions

In older Git versions, checkout syntax may be used for file restore.

git checkout <commit_sha> -- path/to/file.py

This still works in many environments, but git restore is preferred for clarity.

Verify compatibility with current branch

A restored file may compile but still break runtime expectations if related interfaces changed. Run targeted tests and inspect dependent modules after restore.

For config files and schema files, verify environment compatibility before merge.

Recover from accidental restore mistakes

If wrong content was restored, you can reset file back to HEAD quickly.

git restore --source HEAD -- path/to/file.py

This is safer than broad resets and keeps changes scoped to one path.

Document rationale in pull request

When restoring historical content, include rationale and source commit in pull request description. This helps reviewers understand why old code is reintroduced and whether follow-up modernization is needed.

Clear rationale reduces review friction and avoids repeated questions during incident response.

Protect local work before experimenting

If working tree already has unrelated edits, stash or commit them before file restoration experiments. This keeps restore operations clean and prevents accidental overwrite of in-progress changes.

A clean working tree makes diff review straightforward and lowers rollback complexity.

Restore across branches when needed

Sometimes the desired file version exists on another branch rather than an old commit on current branch. You can restore directly from that branch reference and still keep changes local until reviewed.

git restore --source origin/release-2025 -- path/to/file.py

This technique is useful for backporting one file without cherry-picking full commits. It also simplifies emergency patch recovery during release freezes.

Common Pitfalls

• Restoring from incorrect commit because history was not inspected carefully.
• Using branch-level reset when only one file should change.
• Committing restored file without running relevant tests.
• Restoring outdated code that depends on removed interfaces.
• Applying full restore when only a few hunks were needed.

Summary

• Find exact source commit before restoring any file.
• Use git restore --source for explicit file-level recovery.
• Review, stage, and commit only the intended path changes.
• Use patch mode when partial restoration is sufficient.
• Validate compatibility with current branch behavior after restore.