Git Branch Operations: Checkout Files, Replace Branches, Rebase Syntax, and Deletion
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 |
Further Reading
How to Replace One Git Branch with Another
Replacing one Git branch with another is a destructive operation that rewrites the target branch history. The git merge -s ours method is a safe way to achieve this.
The Solution: Using the ours Merge Strategy
The ours merge strategy resolves every conflict by favoring "our" version. By merging main into feature-alpha with the ours strategy, you create a commit with the same content as feature-alpha but with both parents, creating a bridge that allows you to overwrite main.
# 1. Prepare the main branch
git checkout main
git pull
# 2. Create bridge with ours strategy
git checkout feature-alpha
git merge -s ours main
# 3. Fast-forward the main branch
git checkout main
git merge feature-alpha
# 4. Push (force required)
git push --force origin main
Alternative (Hard Reset): git push --force origin feature-alpha:main - shorter but riskier.
Understanding git rebase origin/branch vs git rebase origin branch
The difference between a slash and a space in Git rebase commands is the difference between a simple update and a complete context switch.
Single Argument: git rebase origin/branch
Replays your current branch commits on top of the remote-tracking branch snapshot.
Double Argument: git rebase origin branch
Git treats these as two separate arguments: git rebase <upstream> <working-branch>. Git first checks out <working-branch>, then rebases it onto <upstream>. Since origin is a remote name (not a branch), this usually throws fatal: invalid upstream 'origin'.
| Command | Arguments | Result |
|---|---|---|
git rebase origin/main | One | Rebases current branch onto remote snapshot. |
git rebase origin main | Two | Error - origin is not a valid starting point. |
git rebase main feature | Two | Switches to feature, rebases it onto main. |
Pro Tip: Always run
git fetchbeforegit rebase origin/branchto ensure you have the latest remote snapshot.
How to Delete Local and Remote Branches in Git
Deleting a branch requires a two-step operation: local cleanup and remote cleanup.
# 1. Switch to a safe branch
git checkout main
# 2. Delete locally (-d for merged, -D to force)
git branch -d feature-old-stuff
# 3. Delete on the remote server
git push origin --delete feature-old-stuff
# 4. Prune stale references
git fetch --prune
| Task | Command | When to use |
|---|---|---|
| Delete Merged Local | git branch -d <name> | Daily housekeeping. |
| Force Delete Local | git branch -D <name> | Discard work entirely. |
| Delete Remote | git push <remote> -d <name> | PR is merged and done. |
| Prune Stale Links | git fetch -p | git branch -a shows ghost branches. |
Recovery: If you accidentally deleted a local branch, find the lost commit with git reflog and revive it with git checkout -b <branch_name> <commit_hash>.
