gh-pr-merge-worktree-checkout-trap

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

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 stop here. Optionally clean up local artifacts:

# delete the remote branch (gh's --delete-branch flag also failed silently)
git push origin --delete <feature-branch-name>

# delete the local feature branch (it's already orphaned by the merge)
git branch -D <feature-branch-name>

# remove the worktree you used to develop the feature
git worktree remove .claude/worktrees/<your-feature-worktree>

# prune stale worktree refs
git worktree prune

If state is OPEN or CLOSED (without merge): something else went wrong. The worktree error is masking a real failure. Re-run the merge with --admin or check branch protection / required checks.