create-worktree

---
name: create-worktree
description: Create or reuse a git worktree for a pull request or branch so reviews and work happen in isolation
argument-hint: <name> [--pr <number>] [--branch <ref>]
---

# Git Worktree

Set up an isolated git worktree.

Parse `$ARGUMENTS` to extract:
- The worktree name (required) — used as the directory name under `.worktrees/`
- `--pr <number>` (optional) — checkout a GitHub PR into the worktree using `gh pr checkout`
- `--branch <ref>` (optional) — create the worktree from a specific branch or ref

## Steps

### 1. Determine worktree path

The worktree path is: `<repo-root>/.worktrees/<name>`

For example, if the repo root is `/home/user/src/dlt` and the name is `review-pr-3584`, the worktree path is `/home/user/src/dlt/.worktrees/review-pr-3584`.

Create the `.worktrees` directory if it does not exist:

```
mkdir -p <repo-root>/.worktrees
```

### 2. Create or reuse the worktree

Check if a worktree already exists at that path:

```
git worktree list
```

- **If a worktree already exists** at the target path, reuse it.
  - If `--pr` was given, run `cd <worktree-path> && gh pr checkout <number>` to make sure it is up to date.
  - If `--branch` was given, run `git -C <worktree-path> checkout <ref>`.
- **If no worktree exists** at the target path, create one:
  - If `--pr` was given, first resolve the PR's branch name: `gh pr view <number> --json headRefName -q .headRefName`
  - If `--pr` or `--branch` was given, check `git worktree list` output for any **other** worktree that already has the same branch checked out. If found:
    - Use `AskUserQuestion` to ask the user: "Branch `<branch>` is already checked out in worktree `<existing-path>`. Use that worktree instead?"
    - If the user says yes, use the existing worktree path (skip creation, proceed to step 3 with the existing path).
    - If the user says no, **STOP** — do not create a new worktree. Print a message explaining that the branch is already checked out elsewhere and exit.
  - If no conflict, create the worktree:
    - If `--branch` was given: `git worktree add .worktrees/<name> <ref>`
    - Otherwise: `git worktree add .worktrees/<name> --detach`
    - Callers needing a new branch check it out afterwards: `git checkout --no-track -b <new-branch>`
    - If `--pr` was given, then also: `cd <worktree-path> && gh pr checkout <number>`
- `gh pr checkout` handles fetching, fork tracking, and branch setup automatically.

### 3. Switch cwd

```
cd <worktree-path>
```

Then verify the switch took effect:

```
pwd
```

If `pwd` does not show the worktree path, stop with an error — the cwd did not persist.

### 4. Report

```
Worktree ready: <worktree-path>
```

More agent context in dlt-hub/dlt

16 other files this repository gives its agents.