🧭 Git Worktree Cheat Sheet

Purpose:
git worktree lets you check out multiple branches from the same repository at once, each in its own working directory, sharing the same object database (no extra clone needed).

---

🔧 Core Commands

# List existing worktrees
git worktree list
git worktree list --porcelain   # machine-readable

# Create a new worktree from an existing branch
git worktree add ../path/to/wt feature-branch

# Create both a new worktree AND a new branch
git worktree add -b feature-x ../wt-feature-x

# Create from a remote branch (with tracking)
git worktree add -b bugfix-123 ../wt-bugfix origin/bugfix/123

# Create a detached worktree (no branch)
git worktree add --detach ../wt-review TAG_2025_10_01
# Short form: -d instead of --detach

# Create a worktree without checkout (useful for sparse)
git worktree add --no-checkout ../wt-sparse main

---

🧹 Maintenance & Cleanup

# Remove a worktree (must be clean)
git worktree remove ../wt-feature-x

# Force remove (discard changes)
git worktree remove -f ../wt-feature-x

# Prune stale worktree references
git worktree prune
git worktree prune -n   # dry run

# Lock or unlock a worktree (prevent accidental removal)
git worktree lock ../wt-important
git worktree unlock ../wt-important

# Move or rename a worktree directory
git worktree move ../wt-old ../wt-new

---

🚀 Common Scenarios

1️⃣ Parallel Feature Work
Keep main open while developing a feature:

git worktree add -b feat/login ../wt-login

2️⃣ Hotfix on Old Release

git worktree add -b hotfix-1.2.3 ../wt-hotfix v1.2.3

3️⃣ Detached Code Review

git worktree add -d ../wt-review origin/feature/experimental

4️⃣ Sparse Checkout in Monorepos

git worktree add --no-checkout ../wt-sparse main
cd ../wt-sparse
git sparse-checkout init --cone
git sparse-checkout set packages/app-a

---

🧠 Key Concepts

• Branch exclusivity: A branch can only be checked out in one worktree at a time.
  → Use --detach or a new branch for another worktree.
• Storage efficiency: All worktrees share the same .git/objects, so they’re lightweight.
• Separate HEAD & index: Each worktree has its own HEAD, index, and working directory.
• Hooks & config: You can override per-worktree configuration:

  git config --worktree core.hooksPath .git/hooks

• No nesting: Don’t create a worktree inside another Git repo or worktree.
• Submodules: Managed separately per worktree — reinitialize them as needed.

---

⚠️ Common Issues

Problem	Cause	Fix
“branch … already checked out”	Same branch active in another worktree	Use --detach or create a new branch
Can’t remove worktree (dirty dir)	Uncommitted changes	Commit, stash, or -f
Worktree manually deleted	Orphaned metadata	Run git worktree prune
IDE opens wrong repo	Wrong folder opened	Always open the worktree directory, not the main repo root

---

🩹 Handy One-Liners

# Compact overview of all worktrees
git worktree list --porcelain | awk '/worktree|HEAD|branch/ {print}'

# Create feature worktree from latest main
git fetch origin && git worktree add -b feat/xyz ../wt-xyz origin/main

# Review worktree fixed at merge-base of two branches
git worktree add -d ../wt-base $(git merge-base main feature-x)

---

✅ Pre-removal Checklist

1. Commit or stash changes.
2. Push branch if needed.
3. Delete branch if not needed (git branch -d <branch>).
4. Remove worktree (git worktree remove ../path).
5. Prune stale entries (git worktree prune).