Git Worktrees
Overview
Git worktrees enable checking out multiple branches simultaneously in separate directories, all sharing the same repository. Create a worktree instead of stashing changes or cloning separately.
Core principle:
One worktree per active branch. Switch contexts by changing directories, not branches.
Core Concepts
Concept
Description
Main worktree
Original working directory from
git clone
or
git init
Linked worktree
Additional directories created with
git worktree add
Shared
.git
All worktrees share same Git object database (no duplication)
Branch lock
Each branch can only be checked out in ONE worktree at a time
Worktree metadata
Administrative files in
.git/worktrees/
tracking linked worktrees
Quick Reference
Task
Command
Create worktree (existing branch)
git worktree add
Create worktree with existing branch
git worktree add .. /feature-x feature-x
Create worktree with new branch from current HEAD
git worktree add -b new-feature .. /new-feature
Create worktree with new branch from specific commit
git worktree add -b hotfix-123 .. /hotfix origin/main
Create worktree tracking remote branch
git worktree add --track -b feature .. /feature origin/feature
Create worktree with detached HEAD (for experiments)
git worktree add --detach .. /experiment HEAD~5 List Worktrees
Simple list
git worktree list
Verbose output with additional details
git worktree list -v
Machine-readable format (for scripting)
git worktree list --porcelain Example output: /home/user/project abc1234 [main] /home/user/project-feature def5678 [feature-x] /home/user/project-hotfix ghi9012 [hotfix-123] Remove a Worktree
Remove worktree (working directory must be clean)
git worktree remove .. /feature-x
Force remove (discards uncommitted changes)
git worktree remove --force .. /feature-x Move a Worktree
Relocate worktree to new path
git worktree move .. /old-path .. /new-path Lock/Unlock Worktrees
Lock worktree (prevents pruning if on removable storage)
git worktree lock .. /feature-x git worktree lock --reason "On USB drive" .. /feature-x
Unlock worktree
git worktree unlock .. /feature-x Prune Stale Worktrees
Remove stale worktree metadata (after manual directory deletion)
git worktree prune
Dry-run to see what would be pruned
git worktree prune --dry-run
Verbose output
git worktree prune -v Repair Worktrees
Repair worktree links after moving directories manually
git worktree repair
Repair specific worktree
git worktree repair .. /feature-x Workflow Patterns Pattern 1: Feature + Hotfix in Parallel To fix a bug while feature work is in progress:
Create worktree for hotfix from main
git worktree add -b hotfix-456 .. /project-hotfix origin/main
Switch to hotfix directory, fix, commit, push
cd .. /project-hotfix git add . && git commit -m "fix: resolve critical bug #456" git push origin hotfix-456
Return to feature work
cd .. /project
Clean up when done
git worktree remove .. /project-hotfix Pattern 2: PR Review While Working To review a PR without affecting current work:
Fetch PR branch and create worktree
git fetch origin pull/123/head:pr-123 git worktree add .. /project-review pr-123
Review: run tests, inspect code
cd .. /project-review
Return to work, then clean up
cd .. /project git worktree remove .. /project-review git branch -d pr-123 Pattern 3: Compare Implementations To compare code across branches side-by-side:
Create worktrees for different versions
git worktree add .. /project-v1 v1.0.0 git worktree add .. /project-v2 v2.0.0
Diff, compare, or run both simultaneously
diff .. /project-v1/src/module.js .. /project-v2/src/module.js
Clean up
git worktree remove .. /project-v1 git worktree remove .. /project-v2 Pattern 4: Long-Running Tasks To run tests/builds in isolation while continuing development:
Create worktree for CI-like testing
git worktree add .. /project-test main
Start long-running tests in background
cd .. /project-test && npm test &
Continue development in main worktree
cd .. /project Pattern 5: Stable Reference To maintain a clean main checkout for reference:
Create permanent worktree for main branch
git worktree add .. /project-main main
Lock to prevent accidental removal
git worktree lock --reason "Reference checkout" .. /project-main Pattern 6: Selective Merging from Multiple Features To combine specific changes from multiple feature branches:
Create worktrees for each feature to review
git worktree add .. /project-feature-1 feature-1 git worktree add .. /project-feature-2 feature-2
Review changes in each worktree
diff .. /project/src/module.js .. /project-feature-1/src/module.js diff .. /project/src/module.js .. /project-feature-2/src/module.js
From main worktree, selectively take changes
cd .. /project git checkout feature-1 -- src/moduleA.js src/utils.js git checkout feature-2 -- src/moduleB.js git commit -m "feat: combine selected changes from feature branches"
Or cherry-pick specific commits
git cherry-pick abc1234
from feature-1
git cherry-pick def5678
from feature-2
Clean up
git worktree remove .. /project-feature-1 git worktree remove .. /project-feature-2 Comparing and Merging Changes Between Worktrees Since all worktrees share the same Git repository, you can compare files, cherry-pick commits, and selectively merge changes between them. Compare and Review File Changes Since worktrees are just directories, you can compare files directly:
Compare specific file between worktrees
diff .. /project-main/src/app.js .. /project-feature/src/app.js
Use git diff to compare branches (works from any worktree)
git diff main .. feature-branch -- src/app.js
Visual diff with your preferred tool
code --diff .. /project-main/src/app.js .. /project-feature/src/app.js
Compare entire directories
diff -r .. /project-v1/src .. /project-v2/src Merge Only One File from a Worktree You can selectively bring a single file from another branch using git checkout :
In your current branch, get a specific file from another branch
git checkout feature-branch -- path/to/file.js
Or get it from a specific commit
git checkout abc1234 -- path/to/file.js
Get multiple specific files
git checkout feature-branch -- src/module.js src/utils.js For partial file changes (specific hunks/lines only):
Interactive patch mode - select which changes to take
git checkout -p feature-branch -- path/to/file.js This prompts you to accept/reject each change hunk individually with options: y - apply this hunk n - skip this hunk s - split into smaller hunks e - manually edit the hunk Cherry-Pick Commits from Worktrees Cherry-picking works at the commit level. Since all worktrees share the same repository, you can cherry-pick any commit:
Find the commit hash (from any worktree or git log)
git log feature-branch --oneline
Cherry-pick specific commit into your current branch
git cherry-pick abc1234
Cherry-pick multiple commits
git cherry-pick abc1234 def5678
Cherry-pick a range of commits
git cherry-pick abc1234^ .. def5678
Cherry-pick without committing (stage changes only)
git cherry-pick --no-commit abc1234 Merge Changes from Multiple Worktrees You can merge or cherry-pick from multiple branches:
Merge multiple branches sequentially
git merge feature-1 git merge feature-2
Or use octopus merge for multiple branches at once
git merge feature-1 feature-2 feature-3
Cherry-pick commits from multiple branches
git cherry-pick abc1234
from feature-1
git cherry-pick def5678
from feature-2
Selective Merging - Pick Which Changes to Include Option 1: Selective File Checkout
Get specific files from different branches
git checkout feature-1 -- src/moduleA.js git checkout feature-2 -- src/moduleB.js git commit -m "Merge selected files from feature branches" Option 2: Interactive Patch Selection
Select specific hunks from a file
git checkout -p feature-1 -- src/shared.js Option 3: Cherry-Pick with Selective Staging
Apply changes without committing
git cherry-pick --no-commit abc1234
Unstage what you don't want
git reset HEAD -- unwanted-file.js git checkout -- unwanted-file.js
Commit only what you kept
git commit -m "Selected changes from feature-1" Option 4: Merge with Manual Selection
Start merge but don't auto-commit
git merge --no-commit feature-1
Review and modify staged changes
git status git reset HEAD -- file-to-exclude.js git checkout -- file-to-exclude.js
Commit your selection
git commit -m "Merge selected changes from feature-1" Option 5: Using git restore (Git 2.23+)
Restore specific file from another branch
git restore --source = feature-branch -- path/to/file.js
Interactive restore with patch selection
git
restore
-p
--source
=
feature-branch -- path/to/file.js
Directory Structure Conventions
Organize worktrees predictably:
~/projects/
myproject/ # Main worktree (main/master branch)
myproject-feature-x/ # Feature branch worktree
myproject-hotfix/ # Hotfix worktree
myproject-review/ # Temporary PR review worktree
Naming convention:
Find where the branch is checked out
git worktree list
Either work in that worktree or remove it first
git worktree remove .. /other-worktree Issue: Stale worktree after manual deletion Cause: Deleted worktree directory without using git worktree remove . Solution:
Clean up stale metadata
git worktree prune Issue: Worktree moved manually Cause: Moved worktree directory without using git worktree move . Solution:
Repair the worktree links
git worktree repair
Or specify the new path
git worktree repair /new/path/to/worktree Issue: Worktree on removed drive Cause: Worktree was on removable storage that's no longer connected. Solution:
If temporary, lock it to prevent pruning
git worktree lock .. /usb-worktree
If permanent, prune it
git worktree prune Common Mistakes Mistake Fix Using rm -rf to delete worktree Always use git worktree remove , then git worktree prune if needed Forgetting branch is locked to worktree Run git worktree list before checkout errors Not cleaning up temporary worktrees Remove worktrees immediately after task completion Creating worktrees in nested locations Use sibling directories ( ../project-feature ) not subdirs Moving worktree directory manually Use git worktree move or run git worktree repair after Agent Workflow Integration To isolate parallel agent tasks:
Create worktree for isolated task
git worktree add -b task-123 .. /project-task-123 cd .. /project-task-123
Make changes, run tests, return
cd .. /project To experiment safely with detached HEAD:
Create detached worktree (no branch to clean up)
git worktree add --detach .. /project-experiment cd .. /project-experiment
Experiment, then discard or commit to new branch
git worktree remove --force .. /project-experiment Verification Checklist Before using worktrees: Understand that branches can only be checked out in one worktree Know where worktrees will be created (use sibling directories) Plan cleanup strategy for temporary worktrees When creating worktrees: Use descriptive directory names Verify branch is not already checked out elsewhere Consider using --detach for experiments When removing worktrees: Commit or stash any uncommitted changes Use git worktree remove , not rm -rf Run git worktree prune if directory was deleted manually