Git Worktree Helper

Workflow

• When creating worktrees, the user must explicitly provide the target branch name or branch matching pattern
• If the user does not provide a branch name or pattern, only status checks can be performed; do not default to creating worktrees for all local branches.
• Do not interpret "unspecified scope" as "batch-create worktrees for all branches" to avoid directory proliferation and workspace bloat.

1. Check Current Status First

• Run

  git branch --list '<pattern>'

  to view candidate local branches.
• Run

  git branch -r --list 'origin/<pattern>'

  to view candidate remote branches.
• Summarize the candidate branches in natural language first, clearly distinguishing between local and remote branches, and wait for user confirmation of the target scope.
• If the user selects a remote branch, create the corresponding local branch first before proceeding to create the worktree; do not skip the local branch step by directly using the remote reference.
• Run

  git worktree list --porcelain

  to establish the mapping from existing branches to paths.
• Treat the branch of the current workspace as an existing worktree; do not create a duplicate worktree for it.
• If the user only requests to view the mapping, verify the current status, or confirm which branches are checked out, stop here and do not proceed to the creation step.

2. Select Target Directory Layout

• Default batch layout: Create a directory named

  <repo-name>-worktrees

  at the same level as the repository root directory.
• Each worktree directory name is derived from the branch name, replacing

  /

  with

  ~

  .
• If the user specifies a base directory, prioritize the user-specified value over the default.
• If the user has explicitly provided a target path, use that path directly without deriving the default layout.

/path/to/
├── repo/ # Current project path
└── repo-worktrees/
    ├── skill~git-worktree/ # Corresponding to [skill] development branch skill/git-worktree
    └── feature~login/      # Corresponding to [feature] development branch feature/login

By default,

~

is used instead of

/

to reduce the risk of path collisions when hyphens

-

in the original branch name are involved.

• skill/git-worktree

  ->

  repo-worktrees/skill~git-worktree

• feature/login

  ->

  repo-worktrees/feature~login

• For batch processing, first construct a complete

  branch -> target_path

  plan.
• Check target path uniqueness before execution; if two branches map to the same path, stop immediately and clearly report the conflicting branch pairs.
• If the target path already exists but is not registered as a worktree, stop immediately and expose it as a manual conflict.

3. Create Worktrees

• For batch creation, first list the matching local branches, then derive the target path for each to form a clear creation plan.
• When the scope includes more than one branch, first summarize the plan in natural language, at least specifying the matching branches, corresponding paths, and which branches will be skipped.
• After confirming the plan, run

  git worktree add <path> <branch>

  one by one to execute the creation formally.
• If only one branch is missing, directly use

  git worktree add <path> <branch>

  .

git branch --list 'skill/*'
git branch -r --list 'origin/skill/*'
git worktree list --porcelain
git worktree add /path/to/repo-worktrees/skill~git-worktree skill/git-worktree
git worktree add /path/to/repo-worktrees/feature~login feature/login

4. Verify Results

• After creation, run

  git worktree list --porcelain

  to confirm that the new paths are registered.
• For each newly created worktree, run

  git -C <worktree-path> branch --show-current

  to confirm the checked-out branch is correct.
• Verify that the plan matches the results, especially the quantity and details of the three categories:

  created

  ,

  skipped

  , and

  failed/conflicted

  .
• Clearly report which branches were skipped due to existing worktrees, which paths were newly created, and which branches were unprocessed due to conflicts.

Safety Rules

• Do not create a second worktree for a branch that already has a worktree.
• Do not delete,

  prune

  , or move worktrees unless explicitly requested by the user.
• Do not push remote changes for the purpose of managing local worktrees.
• If path mapping conflicts or target path conflicts are detected, stop immediately and expose them as manual conflicts.

Execution Requirements

• Prioritize using standard Git commands; do not rely on additional scripts.
• For batch processing, first summarize the plan before executing creation to avoid blind one-time implementation.
• No matching branches: This is a normal no-operation result; clearly state "No candidate branches matched, so no worktrees were created".
• Existing worktrees: This is a normal skip; list the branches and their existing paths in the report.
• Path mapping conflicts or target path conflicts: This is a failure; stop execution and wait for manual processing.
• Non-Git repository, non-existent branch, or command execution failure: This is a failure; stop immediately and expose the error.
• When reporting results, clearly distinguish between: existing worktrees, newly created worktrees in this operation, and branches unprocessed due to conflicts.