Git Worktree Setup

---

You are a Git expert specializing in worktree management. The user wants to set up and manage git worktrees for parallel development across multiple branches simultaneously.

What to check first

• Run git worktree list to see existing worktrees and their state
• Verify your main repository has no uncommitted changes with git status
• Check git branch -a to confirm all branches you plan to work on exist
• Inspect .git/worktrees/ directory to understand worktree storage structure

Steps

1. Create your first worktree with git worktree add ../feature-branch feature-branch — this creates a new directory sibling to your main repo linked to the feature-branch
2. Navigate into the new worktree directory and verify it's independent with cd ../feature-branch && git status && git branch
3. Create a new worktree from a non-existent branch using git worktree add -b new-feature ../new-feature main — this branches from main and creates the worktree simultaneously
4. List all active worktrees with git worktree list --verbose to see paths, branches, and detached HEAD states
5. Make changes in one worktree and commit with git add . && git commit -m "message" — this change is isolated to that worktree's branch
6. Repair a broken worktree reference using git worktree repair if you've moved directories or removed worktree folders manually
7. Prune dead worktrees with git worktree prune to clean up worktree entries whose directories no longer exist
8. Remove a worktree completely using git worktree remove ../feature-branch — this unlocks the branch and deletes the directory reference
9. Lock a worktree to prevent accidental removal with git worktree lock ../feature-branch --reason "in progress" and unlock with git worktree unlock ../feature-branch

Code

#!/bin/bash
# Complete git worktree management script

# 1. Initialize: create worktrees for parallel feature development
create_worktree_set() {
    local main_repo=$(pwd)
    local features=("auth-system" "payment-integration" "dashboard-ui")
    
    for feature in "${features[@]}"; do
        echo "Creating worktree for $feature..."
        # Create branch from main if it doesn't exist, then worktree
        git worktree add -b "$feature" "../$feature" main 2>/dev/null || \
        git worktree add "../$feature" "$feature"
    done
}

# 2. Check worktree status
check_worktrees() {
    echo "=== Active Worktrees ==="
    git worktree list --verbose
    
    echo -e "\n=== Worktree Branches ==="
    git worktree list | awk '{print $1}' | while read path; do
        if [ ! -z "$path" ] && [ "$

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change