Git Worktree Cheat Sheet

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
                 [-b <new-branch>] [-B <new-branch>]
                 [--track | --no-track] [--guess-remote | --no-guess-remote]
                 [--orphan] [-q | --quiet] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]] [--expire <time>]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n | --dry-run] [-v | --verbose] [--expire <expire>]
git worktree remove [-f | --force] <worktree>
git worktree repair [<path>...]
git worktree unlock <worktree>

# Syntax: git worktree add <path> <branch>
git worktree add ../feature-auth feature/auth

# The -b flag creates the branch if it doesn't exist
git worktree add -b feature/payments ../payments main

# Useful for inspecting a specific commit or tag
git worktree add --detach ../review-v2 v2.0.0

# If the branch "staging" exists, Git checks it out automatically
git worktree add ../staging

git worktree list
# Example output:
# /home/dev/project        abc1234 [main]
# /home/dev/project-hotfix def5678 [hotfix/login]
# /home/dev/project-feat   789abcd [feature/auth]

git worktree list --porcelain
# worktree /home/dev/project
# HEAD abc1234abc1234abc1234abc1234abc1234abc1234
# branch refs/heads/main
#
# worktree /home/dev/project-hotfix
# HEAD def5678def5678def5678def5678def5678def5678
# branch refs/heads/hotfix/login

# Remove a clean worktree
git worktree remove ../hotfix

# Force-remove a worktree with uncommitted changes
git worktree remove --force ../hotfix

# Move a worktree to a different directory
git worktree move ../hotfix ../fixes/login-hotfix

# Prune stale worktree references
git worktree prune

# Dry-run: see what would be pruned without doing it
git worktree prune --dry-run

# Prune entries older than a certain time
git worktree prune --expire 30.days.ago

# Lock a worktree (with an optional reason)
git worktree lock --reason "on external SSD" ../portable-wt

# Unlock it when the drive is available again
git worktree unlock ../portable-wt

# Check lock status
git worktree list -v

# Repair from inside the main repository
git worktree repair

# Repair and specify worktree paths explicitly
git worktree repair /new/path/to/worktree

# 1. Create a worktree from main for the hotfix
git worktree add -b hotfix/login-crash ../hotfix main

# 2. Fix the bug in the new worktree
cd ../hotfix
# ... make changes ...
git add -A && git commit -m "fix: login crash on empty session"

# 3. Push and open a PR
git push -u origin hotfix/login-crash

# 4. Clean up when done
cd ../my-project
git worktree remove ../hotfix

# Create two feature worktrees side by side
git worktree add -b feature/search ../search main
git worktree add -b feature/notifications ../notifs main

# Work independently in each directory
# ../search/  — search feature
# ../notifs/  — notifications feature

# List all active worktrees
git worktree list

# Clean up after merging
git worktree remove ../search
git worktree remove ../notifs

# Fetch the latest remote branches
git fetch origin

# Create a worktree for the PR branch
git worktree add ../review origin/feature/new-dashboard

# Review the code, run tests, etc.
cd ../review
npm test

# Done reviewing — clean up
cd ../my-project
git worktree remove ../review

# Create a worktree for the release branch
git worktree add ../release-test release/v3.0

# Run the build in the background
cd ../release-test
npm ci && npm run build && npm test

# Compare results, then clean up
cd ../my-project
git worktree remove ../release-test

# Enable automatic remote branch guessing
git config worktree.guessRemote true

# Enable per-worktree configuration
git config extensions.worktreeConfig true