gh-pr-merge-worktree-checkout-traplisted

Diagnose and bypass `gh pr merge --squash --delete-branch` failing with "failed to run git: fatal: 'main' is already used by worktree at ..." when another git worktree has main checked out. Use when: (1) you run gh pr merge and see this exact error, (2) you have multiple worktrees in the repo (e.g. `.claude/worktrees/*`), (3) the error appears even though the GitHub merge itself looks fine. The merge SUCCEEDED on GitHub — only gh's local-side effect (post-merge `git checkout main`) failed. Verify via `gh pr view N --json state,mergedAt`; if state=MERGED, you're done. This also applies to `gh pr checkout` and any other `gh` subcommand that tries to touch the local main branch while another worktree has it claimed. v1.2.0 (2026-05-26) adds the sequential-error variant: if you re-run from the main-repo worktree after the first error, you can then hit "cannot delete branch <feature-branch> used by worktree at <feature-worktree>" — same one-checkout-per-branch invariant, this time applied to the feature branch. Cl
wan-huiyan/agent-traffic-control · ★ 2 · Code & Development · score 79

Install: claude install-skill wan-huiyan/agent-traffic-control

# `gh pr merge` Worktree-on-Main Checkout Trap ## Problem `gh pr merge --squash --delete-branch` (and similar commands) fail with: ``` failed to run git: fatal: 'main' is already used by worktree at '/path/to/another/worktree' ``` even when the user has every right to merge the PR. The error makes it look like the merge failed, prompting the user to retry or panic. **The merge actually succeeded on GitHub.** Only `gh`'s post-merge local side-effect — switching the local working tree to `main` so it's "ready" after the merge — failed because git refuses to check out a branch that's already checked out in another worktree. ## Context / Trigger Conditions You are in the right place if **all** of these are true: - You ran `gh pr merge <number>` (any merge mode: `--squash` / `--merge` / `--rebase`). - The exact error includes `fatal: 'main' is already used by worktree at`. - The repo has multiple `git worktree` entries (run `git worktree list` to confirm). - One of those worktrees is on `main` (or whichever branch the PR merged into). The command's first action is the GitHub merge API call; the local checkout is downstream of that. Failures in the local step do NOT roll back the merge. ## Solution ### Step 1: Verify the merge actually happened ```bash gh pr view <number> --json state,mergedAt # {"state":"MERGED","mergedAt":"YYYY-MM-DDTHH:MM:SSZ"} ``` If `state` is `MERGED`: the PR is merged. The error was a local cleanup side-effect, not a merge failure. **You can sto