Fix git worktree add DWIM when base exists only on remote

[leogdion]

Summary

Fixes a critical bug where git worktree add with a base branch existing only on the remote would silently create a worktree on the wrong branch, leave a stray local ref, and exit successfully.

Root Cause

git worktree add -b <new> <dir> <base> performs DWIM (Do What I Mean) on the base argument. When <base> is a bare name matching a branch that exists only on the remote, git interprets it as "create a local branch tracking origin/<base>" and overrides the -b <new> flag entirely. This results in:

• Worktree checked out on <base> instead of <new>
• <new> branch never created
• Stray local <base> ref left behind to go stale
• Exit status 0 (silent success)

The --no-track flag does not prevent this, as it only governs the upstream, not the branch name.

Changes

git-trees:

• Added _base_sha() helper function that resolves a base argument to a commit SHA by:
  1. First trying the argument as-is (handles local branches and explicit refs)
  2. Falling back to origin/<arg> (handles remote-only branches)
  3. Returning error if neither resolves
• Modified cmd_add() to:
  • Call _base_sha() to resolve the base before creating the worktree
  • Pass the resolved SHA to git worktree add instead of the bare name (eliminates DWIM)
  • Validate that the created worktree's HEAD matches the requested branch name
  • Report clear error if base is unresolvable or if worktree ends up on wrong branch

Tests (smoke.sh):

• Added comprehensive test section "add — remote-only base" covering:
  • Remote-only base creates worktree on requested branch, not base
  • New branch starts at origin/<base> commit
  • No stray local ref left behind
  • New branch tracks its own remote, not the base
  • Explicit origin/<base> form behaves identically
  • Unresolvable base fails with clear error and creates no worktree

Documentation:

• Updated AGENTS.md with new "Git pitfall: a start-point can override -b" section explaining the issue and solution
• Updated README.md to document base resolution behavior
• Updated test coverage documentation in AGENTS.md

Implementation Details

The fix uses two layers of defense:

1. Resolution layer: Convert the base to a SHA before git worktree add sees it, eliminating the DWIM trigger
2. Assertion layer: Verify the worktree's HEAD matches the requested branch, catching any future regressions

This approach is robust because:

• A SHA cannot trigger DWIM (no branch name to match)
• The assertion makes any future regression loud rather than silent
• Error messages clearly identify the problematic base
• No stray refs are created even if something goes wrong

https://claude.ai/code/session_01XvKtUT9b739chxgKFLKAKL

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7e2df535-b873-4d44-b373-062bb0d18c80

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}