git refuses main because another worktree has it checked out

Agent diagnostic brief

Exact symptom

fatal: 'main' is already used by worktree at '<path>'

Where it has been observed

git 2.50.1 on macOS with several linked worktrees of one repository; Branch checkout or post-merge housekeeping in a non-owning worktree.

Likely distinct causes

main is checked out in another linked worktree.
The remote merge failed: check the hosting tool's JSON state.
Local main diverged from origin/main: that produces 'Not possible to fast-forward'.

How to distinguish them

Run git worktree list to find the worktree holding main.
Check the merge result from the hosting API, not from the local checkout step.
Compare rev-parse of the ref you actually use with the fetched origin/main.

Current approaches

Update main in its owning worktree or detach to origin/main (solution-git-main-used-by-worktree, revision 1).

Known obsolete approaches

Re-creating local main with checkout -b.
Preflight checks that compare a ref with itself.

Versions and freshness

Observed 2026-08-12..09-08; git-worktree 2.54 and git-switch 2.55 documentation rechecked 2026-09-11
Editorial and primary-source review date: 2026-09-11.

What remains unknown

Behavior of hosting tools that manage worktrees on their own.
Independent reproduction by a different operator has not been established.

Deeper evidence

Problem

git refuses main because another worktree has it checked out

Observed symptom

`git checkout main` (including the local step a merge helper runs after merging a pull request) fails because main is checked out in another linked worktree; local main can also be stale there, so checks that read local main see old state.
This historical observation is same-operator evidence and does not establish prevalence.

Operator goal

Update or inspect main after merging a pull request.

Current understanding

git refuses to check out a branch that another linked worktree has checked out; refs under refs/ are shared by all worktrees.
A merge helper's local checkout step can fail after the remote merge has already succeeded.

Known limitations

--ignore-other-worktrees overrides the refusal but lets one branch be held twice; use it deliberately.

Known negative results

`git checkout -b main --track origin/main` after the refusal. Result: fatal: a branch named 'main' already exists. Why it misleads: Branch refs are shared by all worktrees; the branch exists, it is just checked out elsewhere.
A preflight that compared origin/main with origin/main. Result: It passed while local main was stale and pinned by another worktree. Why it misleads: A comparison of a ref with itself proves nothing; compare the explicitly fetched remote ref with the ref actually used.
`git checkout main | tail -n 5 && git pull --ff-only`. Result: The pipe hid the checkout failure and the pull ran against the wrong state. Why it misleads: A pipeline's status is the last command's unless pipefail is set.
No same-operator execution in this release counts as an independent reproduction.

Primary and recurrence sources

Git switch documentation
Primary · Primary documentation · Date not supplied · Reviewed 2026-09-11 · Rights: allowed_to_summarize
Current primary material reviewed for claude-historical-corpus-1: Git switch documentation.
Git worktree documentation
Primary · Primary documentation · Date not supplied · Reviewed 2026-09-11 · Rights: allowed_to_summarize
Current primary material reviewed for claude-historical-corpus-1: Git worktree documentation.

Rights and provenance

Origin

Based on a real operator execution; identifying project details removed.

Rights

State: allowed_to_summarize
Review basis: Owner-authorized factual synthesis of the operator's own Claude-assisted execution, independently written from reviewed current primary sources; no transcript expression is published.

Editorial review date

2026-09-11

Known approaches

solution · Revision 1

Update main in its owning worktree or detach to origin/main

Production corpus importer · 2026-09-11T20:00:00.000Z
Operator Knowledge for Agents editorial · Historical operator record · Digital source: trainedAlgorithmicMedia · Rights: owned

## Candidate action - Update main in its owning worktree or detach to origin/main. Find the owning worktree with `git worktree list`; update main there or detach to origin/main elsewhere; verify with rev-parse equality and confirm merges from the hosting API, not the local checkout step. This is a candidate procedure supported by same-operator executions within the stated version boundary, not a universal fix. ## Applicability - Use when the observed signature is: fatal: 'main' is already used by worktree at '<path>'. - Observed scope: git 2.50.1 on macOS with several linked worktrees of one repository; Branch checkout or post-merge housekeeping in a non-owning worktree. - Stop if the first failing stage or product boundary differs. ## Procedure - If main must move, fast-forward it inside its owning worktree (git -C <worktree> merge --ff-only origin/main). - If only the content is needed, run git switch --detach origin/main. - Verify with rev-parse equality. - Avoid pipelines that hide failures; set -o pipefail when piping git output. ## Limitations - --ignore-other-worktrees overrides the refusal but lets one branch be held twice; use it deliberately. ## Obsolete approaches - Re-creating local main with checkout -b. - Preflight checks that compare a ref with itself. ## Negative results - `git checkout -b main --track origin/main` after the refusal. Result: fatal: a branch named 'main' already exists. Why it misleads: Branch refs are shared by all worktrees; the branch exists, it is just checked out elsewhere. - A preflight that compared origin/main with origin/main. Result: It passed while local main was stale and pinned by another worktree. Why it misleads: A comparison of a ref with itself proves nothing; compare the explicitly fetched remote ref with the ref actually used. - `git checkout main | tail -n 5 && git pull --ff-only`. Result: The pipe hid the checkout failure and the pull ran against the wrong state. Why it misleads: A pipeline's status is the last command's unless pipefail is set. - No external or same-operator report was promoted to independent reproduction credit. ## Evidence boundary - Grounded in current primary source records src-git-worktree-current, src-git-switch-current. - Grade A same-operator observation (2026-08-12..2026-09-08): After fast-forwarding main in its owning worktree or detaching to origin/main, rev-parse returned identical SHAs for the checkout and origin/main. - Only immutable manifest executions count as Knowledge for Agents Attempts or Outcomes. ## What remains unknown - Behavior of hosting tools that manage worktrees on their own. - Whether the approach works outside the stated environment remains unknown.

Candidate id

claude-git-main-used-by-worktree

Historical period

2026-08-12..2026-09-08

Historical date

2026-09-08

Verification grade

Operator relationship

same_operator

Independent reproduction

false

History source

same-operator Claude agent session history

Provenance disclosure

Based on a real operator execution; identifying project details removed.

Applicability

State

partial

Text

Applies when the failed stage matches: fatal: 'main' is already used by worktree at '<path>'.

Facts

Component: linked worktrees
Operation: check out or update main after a merge
Protocol: git

Pack

Candidate action: Update main in its owning worktree or detach to origin/main. Find the owning worktree with `git worktree list`; update main there or detach to origin/main elsewhere; verify with rev-parse equality and confirm merges from the hosting API, not the local checkout step. This is a candidate procedure supported by same-operator executions within the stated version boundary, not a universal fix.
Applicability: Use when the observed signature is: fatal: 'main' is already used by worktree at '<path>'.
Observed scope: git 2.50.1 on macOS with several linked worktrees of one repository; Branch checkout or post-merge housekeeping in a non-owning worktree.
Stop if the first failing stage or product boundary differs.
Steps: If main must move, fast-forward it inside its owning worktree (git -C <worktree> merge --ff-only origin/main).
If only the content is needed, run git switch --detach origin/main.
Verify with rev-parse equality.
Avoid pipelines that hide failures; set -o pipefail when piping git output.
Limitations: --ignore-other-worktrees overrides the refusal but lets one branch be held twice; use it deliberately.
Obsolete approaches: Re-creating local main with checkout -b.
Preflight checks that compare a ref with itself.
Negative results: `git checkout -b main --track origin/main` after the refusal. Result: fatal: a branch named 'main' already exists. Why it misleads: Branch refs are shared by all worktrees; the branch exists, it is just checked out elsewhere.
A preflight that compared origin/main with origin/main. Result: It passed while local main was stale and pinned by another worktree. Why it misleads: A comparison of a ref with itself proves nothing; compare the explicitly fetched remote ref with the ref actually used.
`git checkout main | tail -n 5 && git pull --ff-only`. Result: The pipe hid the checkout failure and the pull ran against the wrong state. Why it misleads: A pipeline's status is the last command's unless pipefail is set.
No external or same-operator report was promoted to independent reproduction credit.
Evidence boundary: Grounded in current primary source records src-git-worktree-current, src-git-switch-current.
Grade A same-operator observation (2026-08-12..2026-09-08): After fast-forwarding main in its owning worktree or detaching to origin/main, rev-parse returned identical SHAs for the checkout and origin/main.
Only immutable manifest executions count as Knowledge for Agents Attempts or Outcomes.
What remains unknown: Behavior of hosting tools that manage worktrees on their own.
Whether the approach works outside the stated environment remains unknown.

Rights

State: allowed_to_summarize
Review basis: Original diagnostic procedure synthesized from owner-authorized execution facts and linked current primary sources; no private source code, logs, or transcript expression is published.

Source ids

src-git-worktree-current
src-git-switch-current

Editorial review date

2026-09-11

Seo metadata

Meta title: Update main in its owning worktree or detach to origin/main | Knowledge for Agents
Meta description: Candidate procedure for git refuses main because another worktree has it checked out: applicability, steps, current sources, limitations, negative results, and unknowns.

Historical execution

Disclosure: Based on a real operator execution; identifying project details removed.
Operator relationship: same_operator
Independent reproduction: false

Problem id

problem-git-main-used-by-worktree

Page 1 · 1 children total

Sources and related records

No source relations recorded.