Git Worktree and Branch Management

This skill helps create and manage git worktrees following a consistent directory structure and workflow.

Worktree Directory Structure

When creating worktrees, follow this pattern:

Current project location: ~/projects/user-api

Worktree locations:

• ~/projects/user-api-FEATURENAME (where FEATURENAME is also the branch name)

Examples:

• ~/projects/payment-service-fix-transaction-bug → branch: fix-transaction-bug
• ~/projects/user-api-add-authentication → branch: add-authentication
• ~/projects/analytics-dashboard-update-charts → branch: update-charts

When to Create Worktree vs Branch

Create worktree: Only when user explicitly asks for "worktree" Create branch: When user asks to create/start a branch without mentioning worktree

Creating a Branch (without worktree)

Workflow

1. Check current branch:

   bashCopy

   git branch --show-current
   

2. Determine base branch:

   • If currently on main → create branch from main
   • If NOT on main and user didn't specify → ask user which base branch to use

3. Create and switch to branch:

   bashCopy

   git checkout -b BRANCH_NAME
   

Creating a Worktree

Pre-flight Checks

Before creating a worktree, run the status check script to get all necessary information:

./scripts/check-worktrees.sh

This script provides:

• Current branch
• Remote sync status (whether origin/main is ahead)
• Existing worktrees with their status

Based on the script output:

1. If NOT on main branch:

   • Ask user: "Should the worktree be created from main branch or from the current branch?"
   • Wait for user response before proceeding

2. If on main branch and remote is ahead:

   • Ask: "Remote main has new commits. Would you like to pull before creating the worktree?"
   • If user says yes, pull:
     bashCopy

     git pull origin main
     

Creating the Worktree

1. Determine paths:

   • Get current project directory name (e.g., user-api)
   • Get parent directory path (e.g., ~/projects)
   • Construct worktree path: PARENT_DIR/PROJECT_NAME-FEATURE_NAME

2. Create worktree:

   bashCopy

   git worktree add -b BRANCH_NAME ../PROJECT_NAME-FEATURE_NAME BASE_BRANCH
   

   Where:

   • BRANCH_NAME: The feature branch name (e.g., add-authentication)
   • ../PROJECT_NAME-FEATURE_NAME: The worktree directory path (e.g., ../user-api-add-authentication)
   • BASE_BRANCH: Either main or the current branch (based on pre-flight check)

3. After creation, inform user:

   Copy

   ✓ Worktree created successfully!
   
   Location: /full/path/to/worktree
   Branch: BRANCH_NAME
   
   To navigate to the worktree:
   
     cd /full/path/to/worktree
   
   For better experience, please add the worktree to your session:
   
     /add-dir /full/path/to/worktree
   

Branch Naming

Use descriptive names without enforced prefixes:

• ✓ Good: fix-balance-sheet-bug, add-settings-to-sidebar, update-readme
• ✗ Avoid: feat/, fix/ prefixes (unless user specifically requests them)

Worktree Status Script

The check-worktrees.sh script provides comprehensive git and worktree information:

./scripts/check-worktrees.sh

Output includes:

• Current branch
• Remote sync status (fetch + check if remote is ahead)
• List of existing worktrees
• Worktree age (inactive for >30 days)
• Worktrees with merged branches
• Warning if many worktrees exist (>5)
• Cleanup candidates

When to use:

• Before creating a worktree (pre-flight checks)
• To check existing worktrees
• To identify old worktrees that can be cleaned up

Removing Worktrees

When a feature is complete and merged:

# Remove the worktree
git worktree remove /path/to/worktree

# Delete the branch (if merged)
git branch -d BRANCH_NAME

# Delete remote branch (if needed)
git push origin --delete BRANCH_NAME

Common Scenarios

Scenario 1: User asks "create a branch for fixing authentication bug"

1. Check current branch: git branch --show-current
2. If on main → create branch from main
3. If not on main → ask which base branch to use
4. Create branch: git checkout -b fix-authentication-bug

Scenario 2: User asks "create a worktree for adding payment integration"

1. Run status script: ./scripts/check-worktrees.sh
2. Check script output for current branch and remote status
3. If not on main → ask: create from main or current branch?
4. If on main and remote is ahead → ask: pull before creating?
5. Create worktree: git worktree add -b add-payment-integration ../user-api-add-payment-integration main
6. Provide cd command: cd ~/projects/user-api-add-payment-integration
7. Inform user to add worktree: /add-dir ~/projects/user-api-add-payment-integration

Scenario 3: User asks "switch to feature branch"

1. Check if branch exists locally: git branch --list BRANCH_NAME
2. If exists → switch: git checkout BRANCH_NAME
3. If not → ask if they want to create it or check it out from remote

Important Notes

• Never create worktrees automatically when user just asks for a branch
• Always run ./scripts/check-worktrees.sh before creating worktrees
• Always ask for confirmation when base branch is ambiguous
• Always remind user to add worktree directory to session after creation (/add-dir)
• Use the status script output to make informed decisions about pulling and cleanup