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

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

2. Check repository status

   git status
   git worktree list
   

3. Determine base branch

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

     # 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

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