8.8 KiB
8.8 KiB
Git Worktree Command Reference
Complete reference for git worktree commands.
Basic Commands
Create a New Worktree
# Create worktree with new branch
git worktree add <path> -b <new-branch>
# Create worktree from existing branch
git worktree add <path> <existing-branch>
# Create worktree from specific commit
git worktree add <path> <commit-hash>
Examples:
# New feature branch
git worktree add ../myapp-feature-api -b feature-api
# Use existing branch
git worktree add ../myapp-hotfix hotfix-login
# From specific commit
git worktree add ../myapp-review abc123def
List All Worktrees
# Simple list
git worktree list
# Porcelain format (machine-readable)
git worktree list --porcelain
# With verbose output
git worktree list -v
Output format:
/home/user/myapp abc123 [main]
/home/user/myapp-feature-api def456 [feature-api]
/home/user/myapp-hotfix 789ghi [hotfix-login]
Remove a Worktree
# Remove worktree (must be clean)
git worktree remove <path>
# Force remove (even with uncommitted changes)
git worktree remove <path> --force
Examples:
# Clean removal
git worktree remove ../myapp-feature-api
# Force removal
git worktree remove ../myapp-feature-api --force
Move a Worktree
# Move worktree to new location
git worktree move <old-path> <new-path>
Example:
git worktree move ../myapp-feature-api ~/projects/myapp-feature-api
Prune Stale References
# Clean up references to removed worktrees
git worktree prune
# Dry run (show what would be pruned)
git worktree prune --dry-run
# Verbose output
git worktree prune --verbose
Advanced Usage
Lock/Unlock Worktrees
Prevent a worktree from being automatically pruned or removed.
# Lock a worktree
git worktree lock <path>
# Lock with reason
git worktree lock <path> --reason "Long-running task"
# Unlock a worktree
git worktree unlock <path>
Use cases:
- Worktrees on removable drives
- Network-mounted worktrees
- Long-running background tasks
Create Detached HEAD Worktrees
Useful for reviewing specific commits without creating a branch.
# Checkout specific commit
git worktree add <path> --detach <commit>
# Short form
git worktree add <path> --detach HEAD~5
Example:
# Review a specific commit
git worktree add ../review-commit --detach abc123def
Sparse Checkout in Worktrees
Only check out specific files/directories in a worktree (useful for large repos).
# Create worktree with sparse-checkout
git worktree add <path> <branch>
cd <path>
git sparse-checkout init
git sparse-checkout set <directory1> <directory2>
Example:
# Only checkout src/ and tests/
git worktree add ../myapp-feature-api feature-api
cd ../myapp-feature-api
git sparse-checkout init
git sparse-checkout set src/ tests/
Repair Commands
Repair Worktree
If worktree becomes corrupted or administrative files are damaged.
# Repair a worktree
git worktree repair
# Repair specific worktree
git worktree repair <path>
Configuration Options
Set Worktree Defaults
# Default path for worktrees (relative to repo)
git config worktree.guessRemote true
# Automatically set up remote tracking
git config push.default current
Common Workflows
Workflow 1: Parallel Feature Development
# 1. Create worktree for feature A
git worktree add ../repo-feature-a -b feature-a
# 2. Create worktree for feature B
git worktree add ../repo-feature-b -b feature-b
# 3. Work on both simultaneously
# (open each in separate editor/Claude session)
# 4. When done, merge both
git checkout main
git merge feature-a
git merge feature-b
# 5. Clean up
git worktree remove ../repo-feature-a
git worktree remove ../repo-feature-b
git branch -d feature-a feature-b
Workflow 2: Hotfix During Feature Development
# You're working in a feature worktree
cd ../repo-feature-xyz
# Need to create hotfix
cd <main-repo>
git worktree add ../repo-hotfix -b hotfix-urgent
# Fix the bug
cd ../repo-hotfix
# ... make fixes ...
git add .
git commit -m "Fix urgent bug"
# Merge hotfix
git checkout main
git merge hotfix-urgent
git push
# Continue feature work
cd ../repo-feature-xyz
# ... continue ...
Workflow 3: Code Review Without Switching
# Create worktree for review
git worktree add ../repo-review pr-branch-name
# Review in separate window
cd ../repo-review
# ... review code ...
# Clean up after review
cd <main-repo>
git worktree remove ../repo-review
Troubleshooting Commands
Check Worktree Status
# List all worktrees with details
git worktree list -v
# Check if directory is a worktree
cd <directory>
git rev-parse --git-dir
Find Orphaned Worktrees
# List worktrees that no longer exist
git worktree list --porcelain | grep "^worktree" | awk '{print $2}' | while read dir; do
if [ ! -d "$dir" ]; then
echo "Orphaned: $dir"
fi
done
# Clean them up
git worktree prune
Reset Worktree to Clean State
# Discard all changes
cd <worktree>
git reset --hard HEAD
git clean -fd
# Reset to specific branch state
git fetch origin
git reset --hard origin/<branch>
Integration with Other Git Commands
Fetch/Pull in Worktrees
# Fetch applies to all worktrees (shared .git)
git fetch origin
# Pull in specific worktree
cd <worktree>
git pull origin <branch>
Stash in Worktrees
# Stash is per-worktree
cd <worktree>
git stash push -m "My stash"
# List stashes (shared across worktrees)
git stash list
# Apply stash in different worktree
cd <other-worktree>
git stash apply stash@{0}
Rebase in Worktrees
# Each worktree can have independent rebase operations
cd <worktree>
git rebase main
Performance Tips
Limit Number of Worktrees
- Recommended: 3-5 active worktrees
- Maximum: Depends on disk space and RAM
- Why: Each worktree duplicates working files
Use Sparse Checkout
For large repositories:
git sparse-checkout set <dir1> <dir2>
Reduces disk usage by only checking out necessary files.
Share Object Database
Worktrees automatically share:
.git/objects/(commits, trees, blobs).git/refs/(branches, tags).git/config(configuration)
No duplication of:
- Git history
- Commit objects
- Branch information
Duplicated:
- Working directory files
- Index (staging area)
- Worktree-specific config
Safety and Best Practices
Before Removing Worktrees
# Check for uncommitted changes
cd <worktree>
git status
# Check if branch is merged
git branch --merged main | grep <branch-name>
# Backup if needed
git stash push -m "Backup before removal"
Handling Merge Conflicts
# During merge in worktree
cd <worktree>
git merge main
# If conflicts occur
git status # See conflicting files
# Edit files to resolve
git add <resolved-files>
git commit
Quick Reference Table
| Command | Purpose | Example |
|---|---|---|
git worktree add <path> -b <branch> |
Create with new branch | git worktree add ../wt -b feat |
git worktree add <path> <branch> |
Create from existing | git worktree add ../wt main |
git worktree list |
Show all worktrees | - |
git worktree remove <path> |
Remove worktree | git worktree remove ../wt |
git worktree remove <path> --force |
Force remove | git worktree remove ../wt -f |
git worktree prune |
Clean stale refs | - |
git worktree move <old> <new> |
Move worktree | git worktree move ../wt ~/wt |
git worktree lock <path> |
Prevent pruning | git worktree lock ../wt |
git worktree unlock <path> |
Allow pruning | git worktree unlock ../wt |
git worktree repair |
Fix corrupted worktree | - |
Common Error Messages
"fatal: '' already exists"
Cause: Directory exists
Solution:
rm -rf <path>
# or use a different path
"fatal: invalid reference: "
Cause: Branch name has invalid characters
Solution: Use only alphanumeric and hyphens:
# Bad: feature/my_feature
# Good: feature-my-feature
"fatal: '' is not a working tree"
Cause: Trying to operate on non-worktree directory
Solution:
git worktree list # Find correct path
"fatal: '' is already checked out"
Cause: Branch in use by another worktree
Solution:
# Use a different branch name
git worktree add ../wt -b new-branch-name
Resources
Official Documentation:
Pro Git Book:
- Chapter on worktrees: https://git-scm.com/book/en/v2
Git Worktree Tutorial: