Worktree Management

Standardized patterns for managing git worktrees across the development workflow. All commands that create or manage worktrees should use these patterns.

Purpose

Provides single source of truth for worktree operations, branch naming conventions, and cleanup strategies. Ensures consistent worktree management across all workflows and commands.

Branch Naming Convention

Convert feature descriptions to standardized branch names:

Rules

• Lowercase all text
• Replace spaces with hyphens (-)
• Remove special characters (except hyphens)
• Prefix with type:
  • feat/ for features (default)
  • fix/ for bug fixes (if description contains "fix" or "bug")
  • docs/ for documentation changes
  • refactor/ for code refactoring
  • test/ for test additions

Examples

Bash Pattern

# Generate branch name from description
DESCRIPTION="add dark mode toggle"
PREFIX="feat"  # or "fix" if description contains "fix" or "bug"
BRANCH_NAME=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
BRANCH_NAME="${PREFIX}/${BRANCH_NAME}"

Branch Sanitization for Worktree Paths

When creating worktree directories from branch names, sanitize the branch name:

# Sanitize branch name for directory path
BRANCH="feat/my-feature"
SANITIZED_BRANCH=$(printf '%s' "$BRANCH" | tr -c 'A-Za-z0-9._-' '_')
# Result: feat_my-feature

Why: Slashes in branch names create subdirectories. Sanitizing ensures worktree path is a single directory.

Worktree Creation Pattern

Standard Worktree Path

All worktrees follow this structure:

~/git/{REPO_NAME}/{SANITIZED_BRANCH}/

Example:

• Repo: ai-assistant-instructions
• Branch: feat/add-dark-mode
• Path: ~/git/ai-assistant-instructions/feat_add-dark-mode/

Creation Steps

1. Get repository name:

   REPO_NAME=$(basename $(git rev-parse --show-toplevel))
   

2. Find main worktree path:

   MAIN_PATH=$(git worktree list | head -1 | awk '{print $1}')
   

3. Sync main branch:

   cd "$MAIN_PATH"
   git switch main
   git fetch --all --prune
   git pull
   

4. Sanitize branch name:

   SANITIZED_BRANCH=$(printf '%s' "$BRANCH_NAME" | tr -c 'A-Za-z0-9._-' '_')
   

5. Create worktree:

   WORKTREE_PATH=~/git/${REPO_NAME}/${SANITIZED_BRANCH}
   mkdir -p ~/git/${REPO_NAME}
   git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME" main
   

6. Verify:

   cd "$WORKTREE_PATH"
   git status
   

Worktree Cleanup Pattern

Identify Stale Worktrees

Worktrees are stale if:

1. Branch is merged into main:

   git branch --merged main | grep -q "^  $BRANCH$"
   

2. Remote branch deleted:

   git branch -r | grep -q "origin/$BRANCH"
   # If exit code is 1, remote branch is gone
   

3. Branch shows as [gone]:

   git branch -vv | grep "\[gone\]"
   

Cleanup Steps

1. List all worktrees:

   git worktree list
   

2. For each non-main worktree, check if stale using above criteria

3. Remove stale worktree:

   git worktree remove "$WORKTREE_PATH"
   

4. Delete local branch (if merged or gone):

   git branch -d "$BRANCH_NAME"  # Safe delete (merged only)
   # or
   git branch -D "$BRANCH_NAME"  # Force delete
   

5. Prune administrative files:

   git worktree prune
   

Main Branch Synchronization

Before creating worktrees or after cleanup, sync main:

# Find main worktree
MAIN_PATH=$(git worktree list | head -1 | awk '{print $1}')
cd "$MAIN_PATH"

# Ensure on main branch
git switch main

# Fetch and prune
git fetch --all --prune

# Pull latest
git pull

# Return to original directory
cd -

Common Patterns

Pattern 1: Check if Worktree Exists

WORKTREE_PATH=~/git/repo-name/feat_branch-name
if [ -d "$WORKTREE_PATH" ]; then
  echo "Worktree already exists at $WORKTREE_PATH"
  cd "$WORKTREE_PATH"
else
  echo "Creating new worktree..."
  # Use creation pattern above
fi

Pattern 2: List All Worktrees

git worktree list
# Output format:
# /path/to/main        abc123 [main]
# /path/to/worktree-1  def456 [feat/feature-1]
# /path/to/worktree-2  ghi789 [fix/bug-fix]

Pattern 3: Get Current Worktree Branch

CURRENT_BRANCH=$(git branch --show-current)

Pattern 4: Validate Repository

git rev-parse --is-inside-work-tree
# Exit code 0 = valid git repo
# Exit code != 0 = not a git repo

Commands Using This Skill

• /init-worktree - Primary worktree creation command
• /fix-pr-ci - Creates worktrees for PR branches
• /sync-main - Syncs main across worktrees
• /git-refresh - Cleanup and sync workflow

Related Resources

• worktree-manager agent - Full automation for worktree operations
• worktrees rule - Policy and structure documentation
• branch-hygiene rule - Branch management best practices

Troubleshooting

Issue: "fatal: '$WORKTREE_PATH' already exists"

Cause: Worktree directory exists but not registered with git

Solution:

# Remove the directory
rm -rf "$WORKTREE_PATH"
# Re-create using proper git worktree add command

Issue: "fatal: invalid reference: $BRANCH_NAME"

Cause: Branch name contains invalid characters

Solution: Use branch naming convention from this skill (alphanumeric and hyphens only)

Issue: Worktree shows as "prunable" in git worktree list

Cause: Worktree directory was deleted without using git worktree remove

Solution:

git worktree prune

Issue: Cannot remove worktree - "has changes"

Cause: Uncommitted changes in worktree

Solution:

# Commit or stash changes first
cd "$WORKTREE_PATH"
git stash
cd -
# Then remove
git worktree remove "$WORKTREE_PATH"

Best Practices

1. Always sync main before creating new worktrees
2. Use sanitization for worktree directory names (slashes → underscores)
3. Clean regularly - Remove merged/gone worktrees to save disk space
4. Never work on main - Always create a feature branch worktree
5. One worktree per feature - Isolation prevents conflicts
6. Verify before creating - Check if worktree already exists
7. Prune after cleanup - Run git worktree prune after removing worktrees