forrestchang/worktree-workflow/worktree

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") ``

1. Check repository status

``bash git status git worktree list ``

1. 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" ``

1. 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> ```

1. Verify creation

``bash git worktree list ``

1. 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 ``

1. Ask about the task context

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

1. 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

1. Example interaction:

``` 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