fix(remove): name the detached worktree a branch-only removal leaves behind

[max-sixty]

wt remove <branch> on a worktree whose HEAD has since been detached reported ○ No worktree found for branch <name> and said nothing more, while a directory sat at exactly that branch's path. That line is true — detaching severs the only link git records between a worktree and its branch, so the branch really has no worktree — but it reads as "nothing is there".

The removal now names what it leaves behind:

$ wt remove feature
○ No worktree found for branch feature; a detached worktree is @ ~/repo.feature
↳ To remove the detached worktree, run wt remove ~/repo.feature
✓ Removed branch feature (same commit as main, _)

--format=json carries the same fact as detached_worktree on a branch-only removal, since the human line goes to stderr and "a script checking the exit code sees a clean run" was half of what the issue reported.

The directory is found by matching the worktree-path template, which after a detach is all that still connects the two. That is a weaker association than the rest of the module draws — the template records where a worktree would go, not that this one belongs to that branch — and it is why this only ever adds a line. A mention that occasionally points at a coincidence costs nothing. Three states go unmatched, each because naming them would mislead: a worktree checked out on some other branch (that branch names it), the main worktree (whose path-based removal wt remove refuses, so the hint would be a dead end), and a prunable entry (nothing on disk to point at).

Why this doesn't refuse the removal, and what changed from the earlier commits on this branch

The first four commits made wt remove <branch> refuse in this situation, following the issue's "either remove the worktree, or refuse". Reviewing the premise rather than the menu, refusing was the wrong call:

• Nothing was ever lost. SafeDelete — the default — retains an unintegrated branch, so the only refs the old behavior deleted were ones worktrunk's own six-condition integration test defines as lossless. Even wt remove -D on an unmerged branch leaves the commits reachable: a detached worktree's HEAD is a GC root, and the commit survives gc --prune=now with no branch pointing at it.
• So the refusal protected nothing in three of four cases — --no-delete-branch, unintegrated SafeDelete, and integrated SafeDelete — and in the fourth the user had typed -D.
• It contradicted the addressing model. CLAUDE.md: a path "names what a branch cannot (a detached worktree, one of two checkouts of a branch)". The guard let a branch reach one anyway, via a path template.
• It cost real work: one branch with a detached directory at its path failed a whole multi-branch cleanup.

detached_worktree_for survives to find the path; it no longer decides whether the command runs. The scoping the guard had accumulated over three review rounds — a branch-existence check, a deletion_mode gate — goes with it, since an extra line of output needs no narrowing.

Two fixes from those rounds stand on their own and are kept:

• The double-escaped hint path. format_path_for_display already returns a shell-ready token, so composing it with suggest_command escaped it twice: a worktree under $HOME rendered as wt remove '~/repo.feature', where the quoting suppresses the tilde expansion, and a path needing real quoting came out carrying literal quote characters. Three call sites had it, two predating this branch. format_path_for_display now documents the trap, which until then lived only in pr_mr_switch_hint's docstring.
• live_sibling_checkout's docstring, explaining why that predicate stays on exists() rather than the worktree_is_unusable union the rest of the removal path uses: the two disagree only on a present directory that no longer holds its worktree, and since the predicate only ever gates a deletion, it takes the conservative test.

Testing

test_remove_branch_whose_worktree_was_detached pins the behavior — branch removed, worktree untouched, output naming it — and test_remove_json_reports_detached_worktree pins the machine channel. Snapshots cover the wording, the --no-delete-branch no-op, an unintegrated branch whose ref is retained, a prunable entry (which is named nothing, having nothing on disk), a detached main worktree (where the default-branch refusal is still the accurate answer), and the multi-target case.

Fixes #3769

Thanks to @chachi for the report — the repro runs exactly as written, and the diagnosis in it (the branch→worktree lookup, not detached removal) is what this addresses.

This was written by Claude Code on behalf of max-sixty

[worktrunk-bot]

Holding off on approval per the repo's data-loss policy: the diff edits src/commands/remove.rs (wt remove, the branch-deletion path) and src/git/error.rs's removal hints. The change narrows what gets deleted rather than widening it, but the deletion surface is a human's call — normally I'd request review from @max-sixty, who is the author here.

The guard itself checks out. compute_worktree_path returns the repo root for the default branch in a non-bare repo, so the main worktree does land at the expected path and is_linked() is what excludes it; unwrap_or(true) failing closed there is the right direction. I traced the wt step prune justification too — a live detached worktree enters the sweep as CheckSource::Linked with wt.head as its integration ref while the orphan branch enters as CheckSource::Orphan, so both halves really are candidates in one snapshot.

The hint double-escapes its path. Inline suggestion on src/git/error.rs. format_path_for_display already returns a shell-ready token, and suggest_command escapes it again — so the rendered hint is wt remove '~/repo.feature', not the wt remove ~/repo.feature this PR's description shows. For a path that genuinely needs escaping it stops being cosmetic. Note the same shape already exists outside this diff, in the "gained a worktree since it was selected" bail in prepare_worktree_removal (src/commands/repository_ext.rs, the arm matching RemoveTarget::BranchOnly that calls suggest_command("remove", &[&path], &[]) on a format_path_for_display result) — happy to push a commit fixing both if you want them to move together.

#3770 is still open. This supersedes it, but nothing has closed it yet, so the two now sit in the list with identical titles.

One residual asymmetry, for your judgment rather than a change request: prune reaches the stranded state this guard refuses to create, when the two halves disagree on integration. If the detached worktree's HEAD is unmerged (not removable) but the branch it used to hold is integrated, the orphan-branch candidate is deleted and the detached worktree stays registered — branch gone, worktree left, which is the shape the new error calls out. The docstring's reasoning covers the case where prune can clean up both; this is the case where it cleans up only the branch.

[worktrunk-bot]

Two behaviors #3770's last review round turned up in the identical guard, neither of which is in this diff — flagging them here since this is the version that lands. Both were built and pinned on fix/issue-3769 (94f7f8b0, f1f29b61), green on test (linux|macos|windows) plus codecov/patch, so they carry over as-is.

1. The guard preempts the branch-existence check, and claims a branch that isn't there. prepare_worktree_removal's branch-only arm is what reports a typo or a remote-only name (the exists_locally() / RemoteOnlyBranch block in src/commands/repository_ext.rs). detached_worktree_for fires ahead of it, so a name that is not a local branch but whose templated path holds a detached worktree reports a branch that doesn't exist:

$ git branch -D feature          # detach first, then drop the ref
$ wt remove feature
✗ Branch feature has no worktree; the one @ /tmp/repro/myproject.feature is detached

Without the detached worktree at that path the same command says No branch named feature. Fix is one check at the top of detached_worktree_for:

    // Downstream, `prepare_worktree_removal` is what reports a typo, a deleted
    // branch, or a remote-only name; a guard that fires ahead of it would
    // assert a branch that doesn't exist. `exists_locally` reports a failed
    // lookup as `false` rather than an error, so this can't fail closed — but
    // the same call downstream then refuses the removal, so a guard skipped
    // that way still never deletes a ref.
    if !repo.branch(branch).exists_locally().unwrap_or(true) {
        return None;
    }
    let expected = compute_worktree_path(repo, branch, config).ok()?;

2. It fires when the removal wasn't going to delete the ref. Branch-only removal under --no-delete-branch (or [remove] delete-branch = false) deletes nothing — it prints ○ No worktree found for branch … and exits 0. The guard makes it exit 1, so for anyone running delete-branch = false every wt remove <branch> whose worktree has been detached becomes a hard failure, protecting nothing. deletion_mode is already in scope at the call site:

                if let Some(detached) = worktrees
                    .filter(|_| !deletion_mode.should_keep())
                    .and_then(|wts| detached_worktree_for(repo, config, &branch, wts))
                {

The cost of that gate is that what comes back is the ○ No worktree found for branch feature line, which is inaccurate for exactly the reason #3769 opens with — making it accurate without making it fatal is a separate message-design call.

One case the gate's reasoning covers but deliberately doesn't gate: an unintegrated branch under SafeDelete retains its ref too (BranchDeletionOutcome::NotDeleted, exit 0), but only the downstream deletion attempt knows that — Repository::integration_reason isn't free at guard time — so those refuse at exit 1 rather than exiting 0. That's a behavior change worth naming in a comment; refusing is the conservative direction since the path it names is still on disk.

Tests

Three on fix/issue-3769, all snapshot-based alongside the existing detached-worktree cases in tests/integration_tests/remove.rs:

• test_remove_missing_branch_with_detached_worktree_at_its_path — detach, git branch -D, then wt remove <name> reports ✗ No branch named … with the branch-list hint.
• test_remove_branch_with_detached_worktree_keeping_branch — --no-delete-branch exits 0 with ○ No worktree found for branch ….
• test_remove_unmerged_branch_with_detached_worktree_refuses — pins the SafeDelete-unmerged refusal at exit 1.

[worktrunk-bot]

Both behaviors from the last round are fixed and pinned, and #3770 is closed now, so that observation is stale. The exists_locally gate lands ahead of compute_worktree_path, and gating on !deletion_mode.should_keep() reads correctly against the config path too — handle_remove_command folds [remove] delete-branch into delete_branch before passing !delete_branch as keep_branch, so Keep covers the config form as well as the flag.

The help text still describes the refusal as unconditional. Inline suggestion on src/cli/mod.rs. The added paragraph in the Branch cleanup section says wt remove <branch> "refuses instead and names the path" — written when the guard was unconditional. After this push, someone running delete-branch = false gets ○ No worktree found for branch <name> and exit 0, which is the exact message #3769 opens with. The section is about branch deletion, so context does most of the work, but the sentence is the one place a delete-branch = false user would go looking, and it currently promises them a protection they don't get. Applying the suggestion desyncs the three rendered mirrors and help_remove_long.snap — cargo run -- hook pre-merge --yes regenerates both sets.

Minor, take it or leave it: detached_worktree_for now runs rev-parse --verify refs/heads/<branch> before the template match, and prepare_worktree_removal's branch-only arm runs the same lookup a few lines downstream, so every branch-only removal pays it twice. Ordering the existence check after the find is semantically identical — all three are ANDed predicates over the same inputs — and skips the subprocess entirely in the common case where no detached worktree sits at the templated path. The comment explaining why the check exists reads the same in either position.

[worktrunk-bot]

The reworded paragraph matches the guard's gate — !deletion_mode.should_keep() is what makes --no-delete-branch / [remove] delete-branch = false fall through to the no-op, and all three rendered mirrors plus help_remove_long.snap moved with src/cli/mod.rs in the same commit. That was the last open finding; nothing new on this push.

Still not approving, per the repo's data-loss policy for the wt remove deletion surface — same hold as my first review, not a fresh concern.

[worktrunk-bot]

The rewrite from refusal to annotation reads as the right call, and the premise holds: SafeDelete retains an unintegrated branch, so in three of four cases the old guard was refusing to protect a ref nothing was going to delete. Three findings on the new shape, none blocking.

Following the new hint after -D drops the last reference to the commits. The description's case for dropping the refusal is that nothing is lost because "a detached worktree's HEAD is a GC root, and the commit survives gc --prune=now with no branch pointing at it" — which is true right up until the user follows the hint the same command just printed. wt remove <path> on a detached worktree renders (detached HEAD, no branch to delete) and nothing else — the detached arm in handle_remove_output has no reachability check — so the one command that reads most like "nothing to lose" is the one that unroots the commit. Pre-existing behavior on the path spelling; what's new is that this PR routes the user there in one guided step, immediately after -D deleted the ref that was keeping the commit named. Whether the hint should say anything when the detached HEAD isn't reachable from any ref, or whether typing -D is consent enough, is your call rather than a change request.

Reproduced against this branch's binary

$ git worktree add -b feature ../repo.feature && git -C ../repo.feature checkout --detach HEAD
$ git -C ../repo.feature commit -m "unmerged work"   # then detach

$ wt remove -D feature --foreground --yes
○ No worktree found for branch feature; a detached worktree is @ /tmp/…/repo.feature
↳ To remove the detached worktree, run wt remove /tmp/…/repo.feature
✓ Removed branch feature (--force-delete)

$ wt remove /tmp/…/repo.feature --foreground --yes
◎ Removing worktree @ /tmp/…/repo.feature... (detached HEAD, no branch to delete)
✓ Removed worktree @ /tmp/…/repo.feature (detached HEAD, no branch to delete) (3 files · 68 B)

$ git log --all --oneline
7c01f45 init                      # the unmerged commit is no longer reachable
$ git cat-file -e ba31643 && echo present
present                           # unreferenced, GC-eligible

Under the default SafeDelete the branch is retained, so the commit stays named and the sequence is harmless — -D is what makes it reachable.

The main-worktree exclusion is load-bearing and untested. is_linked().unwrap_or(true) in detached_worktree_for is the only thing keeping wt remove -D main from naming the repo root: compute_worktree_path returns repo_root for the default branch in a non-bare repo (the if !is_bare && branch == default_branch early return in src/commands/worktree/resolve.rs), and a detached main worktree is branch: None, not prunable, and path-matching — so every other predicate in the find passes. test_remove_default_branch_with_detached_main_worktree doesn't reach the annotation at all: check_not_default_branch errors first, and it only fires when !deletion_mode.is_force(). With -D the flow runs all the way through, which is where the guard earns its keep. Inline suggestion adds that case; it needs cargo insta test --accept --test integration for the new snapshot.

Verified against this branch's binary

$ git checkout --detach HEAD          # in the main worktree
$ wt remove -D main --foreground --yes
○ No worktree found for branch main
✓ Removed branch main (--force-delete)

No a detached worktree is @ … line — correct, and nothing currently pins it.

Minor: a locked detached worktree gets a hint that can't run. The docstring excludes the main worktree because "the hint would name a command that can't run"; a locked worktree is the same shape and isn't excluded — wt remove feature prints To remove the detached worktree, run wt remove /tmp/…/repo.feature, and that command exits 1 with Cannot remove repo.feature, worktree is locked. It's a soft dead end, since the lock error carries its own git worktree unlock hint, so narrowing the docstring's claim rather than adding a fourth exclusion may be the whole fix.

Holding approval per the repo's data-loss policy — the diff edits src/commands/remove.rs's branch-deletion path. Same standing hold as my earlier reviews, not a fresh concern.

[worktrunk-bot]

Both findings from the last round are closed: test_remove_default_branch_force_with_detached_main_worktree reaches detached_worktree_for with -D and pins the is_linked() exclusion (snapshot shows the bare ○ No worktree found for branch main, no annotation), and the docstring now states what the exclusion actually turns on. That rewording checks out — GitError::CannotRemoveMainWorktree renders its title alone, while GitError::WorktreeLocked carries To unlock, run git worktree unlock <path>, so "the hint leads somewhere" is the distinction that separates them, not "the command succeeds".

codecov/patch is red at 97.05% (66/68), and both misses are pre-existing. They're src/output/handlers.rs's RetainedCheckedOut and RetainedRaced arms, where eprintln!("{}", info_message(&branch_info)); became announce_branch_info(); — the same statement rewritten in place. Codecov's own base report marks both lines as misses on 91b7bef, so the patch counts two lines this change didn't make uncovered. Every other file in the diff is 100%. Handing over the arithmetic per the repo's coverage policy rather than proposing test churn to move the number; covering those two arms is a separate, pre-existing question.

affected tests (linux, advisory) failed in the test-setup step, not the suite: apt-get got 403 Forbidden from packages.microsoft.com for both the azure-cli and prod repos. Transient infra — test (linux), fast-checks, and code-coverage all pass on this head.

Holding approval per the repo's data-loss policy — the diff edits src/commands/remove.rs's branch-deletion path. Same standing hold as my earlier reviews. The -D-then-follow-the-hint observation from the last round stands as your call, not a change request.

Coverage arithmetic

$ curl -sL "$API/compare/?base=91b7beff…&head=37562f5c…" | jq '.files[] | select(.has_diff) | {name: .name.head, patch: .totals.patch}'
src/commands/remove.rs         33/33  100%
src/output/handlers.rs         19/21   90.47%
src/commands/repository_ext.rs   2/2   100%
src/commands/picker/mod.rs       6/6   100%
src/commands/worktree/types.rs   5/5   100%
src/git/repository/worktrees.rs  1/1   100%
                                66/68  97.05%   (target 98.13%)

$ # the two misses
1333: +            announce_branch_info();      # RetainedCheckedOut arm
1341: +            announce_branch_info();      # RetainedRaced arm

$ # same statements on the base, before this PR touched them
$ curl -sL "$API/file_report/src/output/handlers.rs?sha=91b7beff…" \
    | jq -r '.line_coverage[] | select(.[0] == 1297 or .[0] == 1305)'
[1297, 1]    # 1 = miss
[1305, 1]