How to Checkout a Single File from Another Git Branch
Sometimes, you may want to retrieve a specific file from another branch in a Git repository without switching branches completely. This is particularly useful when you want to grab a specific version of a file for debugging, rollback, or review.
In this guide, we’ll walk through how to checkout a single file from another branch using Git. We’ll cover multiple scenarios with examples and best practices.
Why This is Useful
- Revert or test a previous version of a file
- Compare changes between branches
- Avoid conflicts from switching the full branch
- Maintain working directory without resets
1. Basic Git Checkout Syntax
The simplest way to checkout a file from another branch is:
git checkout <branch-name> -- <path-to-file>
✅ Example
Let’s say you want to get README.md from the develop branch while on main:
git checkout develop -- README.md
This will replace the current README.md in your working directory with the version from develop.
2. Checkout a File to a Different Name
You can also checkout the file from another branch and save it under a different name:
git show develop:README.md > README.develop.md
This is useful if you want to compare two versions side-by-side.
3. Checking Out a File in a Subdirectory
git checkout feature-x -- src/utils/helpers.py
Make sure you provide the relative path from the root of the repo.
4. Listing Files in Another Branch
If you’re unsure what the exact path of the file is in the other branch:
git ls-tree -r <branch-name> --name-only
Example
git ls-tree -r develop --name-only | grep requirements.txt
5. Restore File from Another Branch (Git 2.23+)
Starting with Git 2.23, you can also use git restore:
git restore --source <branch-name> <path-to-file>
Example
git restore --source develop README.md
This is the modern equivalent of git checkout and more descriptive.
6. Caution: This Overwrites the File
Be aware that both git checkout and git restore will overwrite your current file.
If you want to keep your local changes, stash them first:
git stash push -m "before file restore"
git checkout <branch> -- <file>
git stash pop
7. Compare File Differences (Optional)
To view the differences without checking out the file:
git diff <branch-name> -- <file>
This shows the changes between your current working file and the one in another branch.
Summary Table
| Task | Command Example |
|---|---|
| Checkout a file from another branch | git checkout develop -- myfile.py |
| Save file under different name | git show develop:myfile.py > myfile-dev.py |
| Use restore instead of checkout | git restore --source develop myfile.py |
| See diff between branches | git diff develop -- myfile.py |
| List files in a branch | git ls-tree -r develop --name-only |