feat: diagnose existing-branch failures in wtclone add

`wtclone add` previously rejected any pre-existing local branch ref with
a single generic message ("already exists locally; use 'git worktree
add ...' directly"). That conflated four meaningfully different states
and gave the same suggestion to all of them, including ones where it
was wrong (branch checked out elsewhere) or unsafe (local diverged from
origin and the user might lose unpushed work).

Replace with a `diagnose_existing_branch` helper that distinguishes:

  1. branch checked out in another worktree → name the worktree path;
  2. orphan ref matching origin/<branch> → "safe to attach" + the
     single attach command;
  3. orphan ref diverged from origin → show ahead/behind counts and
     offer both the attach-and-keep path and the `branch -D` +
     recreate path;
  4. orphan ref with no origin counterpart → flag as local-only and
     suggest the direct attach.

Move `git fetch origin --prune` ahead of the existing-branch check so
the divergence calculation in case 3 runs against fresh remote-tracking
refs rather than potentially stale ones. The success path still calls
fetch exactly once.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Matthieu Ciappara

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - `wtclone rm` now detects gitignored entries (caches, build artifacts, vendored deps) before delegating to `git worktree remove`. These pass git's cleanliness check but block the final `rmdir` with the cryptic `failed to delete '...': Directory not empty`. The new pre-check fails with a message that names the offending entries and points to the two remediation paths: `wtclone rm <branch> --force`, or `git -C <wt_path> clean -fdX` to clean first. Behavior is unchanged — `--force` still bypasses the check.
+- `wtclone add` now diagnoses the "branch already exists locally" failure with a tailored message per case: (1) branch checked out in another worktree (shows the worktree path); (2) orphan ref matching `origin/<branch>` (suggests the safe `git worktree add <branch>` attach); (3) orphan ref diverged from origin (reports ahead/behind counts and offers both attach-and-keep and `branch -D` + recreate paths); (4) orphan ref with no remote counterpart (suggests local-only attach). The `fetch origin` step now runs before the existing-branch check so the diagnosis works against fresh remote-tracking refs.
 
 ## [0.2.0] - 2026-04-24
 

bin/wtclone

@@ -134,19 +134,87 @@ cmd_init() {
 
 # ---- cmd_add -------------------------------------------------------------
 
+# Print a tailored diagnosis for an existing refs/heads/<branch> that blocks
+# `wtclone add`. Distinguishes (1) checked out in another worktree, (2) orphan
+# ref matching origin, (3) orphan ref diverged from origin, (4) orphan ref with
+# no origin counterpart. Writes to stderr; caller is responsible for exit.
+diagnose_existing_branch() {
+  local branch="$1" checked_out_at
+  checked_out_at=$(git --git-dir=.bare worktree list --porcelain | awk -v b="refs/heads/$branch" '
+    $1=="worktree" { path=$2 }
+    $1=="branch" && $2==b { print path; exit }
+  ')
+  if [ -n "$checked_out_at" ]; then
+    {
+      printf "wtclone: branch '%s' is already checked out at:\n" "$branch"
+      printf "    %s\n" "$checked_out_at"
+      printf '\n'
+      printf "wtclone: a branch can only be checked out in one worktree at a time.\n"
+    } >&2
+    return
+  fi
+
+  local local_sha
+  local_sha=$(git --git-dir=.bare rev-parse --short "refs/heads/$branch")
+
+  if ! git --git-dir=.bare show-ref --verify --quiet "refs/remotes/origin/$branch"; then
+    {
+      printf "wtclone: branch '%s' exists locally with no worktree attached (orphan ref).\n" "$branch"
+      printf "    local:  refs/heads/%s @ %s\n" "$branch" "$local_sha"
+      printf "    origin: (no refs/remotes/origin/%s — branch is not on the remote)\n" "$branch"
+      printf '\n'
+      printf "wtclone: this is a local-only branch; attach it with:\n"
+      printf "    git worktree add %s\n" "$branch"
+    } >&2
+    return
+  fi
+
+  local origin_sha
+  origin_sha=$(git --git-dir=.bare rev-parse --short "refs/remotes/origin/$branch")
+  if [ "$local_sha" = "$origin_sha" ]; then
+    {
+      printf "wtclone: branch '%s' exists locally with no worktree attached (orphan ref).\n" "$branch"
+      printf "    local:  refs/heads/%s @ %s\n" "$branch" "$local_sha"
+      printf "    origin: refs/remotes/origin/%s @ %s\n" "$branch" "$origin_sha"
+      printf '\n'
+      printf "wtclone: local matches origin — safe to attach with:\n"
+      printf "    git worktree add %s\n" "$branch"
+    } >&2
+    return
+  fi
+
+  local ahead behind
+  ahead=$(git --git-dir=.bare rev-list --count "refs/remotes/origin/$branch..refs/heads/$branch" 2>/dev/null || echo "?")
+  behind=$(git --git-dir=.bare rev-list --count "refs/heads/$branch..refs/remotes/origin/$branch" 2>/dev/null || echo "?")
+  {
+    printf "wtclone: branch '%s' exists locally with no worktree attached (orphan ref).\n" "$branch"
+    printf "    local:      refs/heads/%s @ %s\n" "$branch" "$local_sha"
+    printf "    origin:     refs/remotes/origin/%s @ %s\n" "$branch" "$origin_sha"
+    printf "    divergence: %s ahead, %s behind origin/%s\n" "$ahead" "$behind" "$branch"
+    printf '\n'
+    printf "wtclone: local and origin differ. Choose:\n"
+    printf "  - attach the local branch (keeps any unpushed work):\n"
+    printf "      git worktree add %s\n" "$branch"
+    printf "  - discard the local ref and re-create from origin/%s:\n" "$branch"
+    printf "      git --git-dir=.bare branch -D %s\n" "$branch"
+    printf "      wtclone add %s\n" "$branch"
+  } >&2
+}
+
 cmd_add() {
   local branch="${1:-}" base="${2:-}"
   [ -n "$branch" ] || die "usage: wtclone add <branch> [base]"
 
   ensure_layout
 
-  if git --git-dir=.bare show-ref --verify --quiet "refs/heads/$branch"; then
-    die "branch '$branch' already exists locally; use 'git worktree add $branch' directly"
-  fi
-
   log "fetching origin"
   git --git-dir=.bare fetch origin --prune 1>&2
 
+  if git --git-dir=.bare show-ref --verify --quiet "refs/heads/$branch"; then
+    diagnose_existing_branch "$branch"
+    exit 1
+  fi
+
   if git --git-dir=.bare show-ref --verify --quiet "refs/remotes/origin/$branch"; then
     log "worktree $branch will track origin/$branch"
     git worktree add -b "$branch" "$branch" "origin/$branch" 1>&2

test/wtclone.bats

@@ -343,7 +343,7 @@ make_v010_layout() {
   rm -rf "$src" "$dest"
 }
 
-@test "add: refuses when branch already exists locally" {
+@test "add: refuses when branch is checked out in another worktree" {
   local src dest
   src=$(mktemp -d); dest=$(mktemp -d)
   make_fixture_remote "$src"
@@ -352,7 +352,66 @@ make_v010_layout() {
   cd "$dest/proj"
   run "$BIN" add main
   [ "$status" -ne 0 ]
-  [[ "$output" == *"already exists locally"* ]]
+  [[ "$output" == *"already checked out at"* ]]
+  [[ "$output" == *"$dest/proj/main"* ]]
+
+  rm -rf "$src" "$dest"
+}
+
+@test "add: orphan ref matching origin → suggests safe attach" {
+  local src dest
+  src=$(mktemp -d); dest=$(mktemp -d)
+  make_fixture_remote "$src"
+  WTCLONE_ROOT="$dest" "$BIN" init "$src" proj 1>/dev/null
+
+  cd "$dest/proj"
+  # Create a refs/heads/staging pointing at origin/staging, no worktree.
+  git --git-dir=.bare branch staging origin/staging
+
+  run "$BIN" add staging
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"orphan ref"* ]]
+  [[ "$output" == *"local matches origin"* ]]
+  [[ "$output" == *"git worktree add staging"* ]]
+
+  rm -rf "$src" "$dest"
+}
+
+@test "add: orphan ref diverged from origin → shows ahead/behind and both options" {
+  local src dest
+  src=$(mktemp -d); dest=$(mktemp -d)
+  make_fixture_remote "$src"
+  WTCLONE_ROOT="$dest" "$BIN" init "$src" proj 1>/dev/null
+
+  cd "$dest/proj"
+  # Orphan ref pointing at origin/main (different SHA than origin/staging).
+  git --git-dir=.bare branch staging origin/main
+
+  run "$BIN" add staging
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"orphan ref"* ]]
+  [[ "$output" == *"local and origin differ"* ]]
+  [[ "$output" == *"divergence:"* ]]
+  [[ "$output" == *"branch -D staging"* ]]
+  [[ "$output" == *"git worktree add staging"* ]]
+
+  rm -rf "$src" "$dest"
+}
+
+@test "add: orphan ref with no origin counterpart → suggests local-only attach" {
+  local src dest
+  src=$(mktemp -d); dest=$(mktemp -d)
+  make_fixture_remote "$src"
+  WTCLONE_ROOT="$dest" "$BIN" init "$src" proj 1>/dev/null
+
+  cd "$dest/proj"
+  git --git-dir=.bare branch only-local origin/main
+
+  run "$BIN" add only-local
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"orphan ref"* ]]
+  [[ "$output" == *"not on the remote"* ]]
+  [[ "$output" == *"git worktree add only-local"* ]]
 
   rm -rf "$src" "$dest"
 }