Git Worktree Workflow

Create a git worktree to enable parallel development on multiple branches.

Arguments

• •First argument: New branch name (required)
• •Second argument: Base branch to create from (optional, auto-detects default branch)

Worktree Directory Convention

Worktrees are created in ../worktrees/<repo-name>-<branch-name> relative to the main repository.

This naming convention:

• •Keeps all worktrees in a shared worktrees directory above the repo
• •Includes repo name to avoid conflicts when working on multiple projects
• •Includes branch name for easy identification

Example: If working in /home/user/projects/my-app on branch feature-auth, the worktree path would be /home/user/projects/worktrees/my-app-feature-auth

Instructions

1. •

   Get repository info

   bash

   # Get repo root and name
   repo_root=$(git rev-parse --show-toplevel)
   repo_name=$(basename "$repo_root")
   

2. •

   Check repository status

   bash

   git status
   git worktree list
   

3. •

   Determine base branch

   • •Use the second argument if provided
   • •Otherwise, detect default branch:
     bash

     # Try remote HEAD first
     git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
     # Fallback to checking main/master
     git show-ref --verify --quiet refs/remotes/origin/main && echo "main"
     git show-ref --verify --quiet refs/remotes/origin/master && echo "master"
     

4. •

   Create the worktree

   bash

   # Define paths
   branch_name="<first-argument>"
   # Convert slashes in branch name to dashes for directory name
   # e.g., "feature/user-auth" -> "feature-user-auth"
   dir_safe_branch="${branch_name//\//-}"
   worktrees_dir="$(dirname "$repo_root")/worktrees"
   worktree_path="$worktrees_dir/${repo_name}-${dir_safe_branch}"
   
   # Create worktrees directory if needed
   mkdir -p "$worktrees_dir"
   
   # Fetch latest from base branch
   git fetch origin <base-branch>
   
   # Create worktree with new branch from base
   git worktree add "$worktree_path" -b "$branch_name" origin/<base-branch>
   

5. •

   Verify creation

   bash

   git worktree list
   

6. •

   Report to user

   • •Confirm the new worktree path
   • •Show which branch it's based on
   • •Remind user how to navigate: cd <worktree_path>

Temporary Branch Handling

When a branch has a temporary name (pattern: wt-* or similar timestamp-based names), you should:

1. •

   Detect temporary branch

   bash

   branch=$(git branch --show-current)
   if [[ "$branch" == wt-* ]]; then
       # This is a temporary branch
   fi
   

2. •

   Ask about the task context

   • •What feature or fix is being worked on?
   • •Is there an issue ID (e.g., ISSUE-123)?
3. •

   Suggest and rename the branch

   bash

   # Rename to a meaningful name based on the task
   git branch -m <old-name> <new-name>
   

   Naming conventions:

   • •feature/<description> - New features
   • •fix/<description> - Bug fixes
   • •refactor/<description> - Code refactoring
   • •docs/<description> - Documentation changes
   • •ISSUE-123-<description> - When linked to an issue tracker
4. •

   Example interaction:

   code

   User: Let's add user authentication
   
   Claude: I notice the current branch has a temporary name 'wt-1706789012'.
   Based on your task, I'll rename it to something more descriptive.
   
   [Runs: git branch -m wt-1706789012 feature/user-auth]
   
   Branch renamed to 'feature/user-auth'. Now let's implement the authentication...
   

Cleanup Instructions

When the user wants to remove a worktree:

# Get current repo info
repo_root=$(git rev-parse --show-toplevel)
repo_name=$(basename "$repo_root")
branch_name="<branch-name>"
# Convert slashes in branch name to dashes for directory name
dir_safe_branch="${branch_name//\//-}"
worktrees_dir="$(dirname "$repo_root")/worktrees"

# Remove a specific worktree
git worktree remove "$worktrees_dir/${repo_name}-${dir_safe_branch}"

# Or manually delete and prune
rm -rf "$worktrees_dir/${repo_name}-${dir_safe_branch}"
git worktree prune

# List remaining worktrees
git worktree list

Examples

# Create a feature branch worktree from auto-detected default branch
/worktree feature/user-auth

# Create a feature branch worktree from main
/worktree feature/user-auth main

# Create a hotfix worktree from production branch
/worktree hotfix/login-bug production

Integration with claude-wt

This skill works with the claude-wt bash script:

1. •claude-wt creates a worktree with a temporary branch name (e.g., wt-1706789012)
2. •The worktree is created at ../worktrees/<repo-name>-<branch-name>
3. •Claude Code starts in the worktree directory
4. •When the user describes their task, rename the branch appropriately
5. •Continue with the implementation

Red Flags

Never:

• •Proceed with a temporary branch name (wt-*) without asking about renaming
• •Create worktrees in directories that don't follow the convention

Always:

• •Use the path convention: ../worktrees/<repo-name>-<branch-name>
• •Detect and offer to rename temporary branches
• •Auto-detect the default branch if not specified
• •Verify worktree creation with git worktree list