gastownhall/beads · error

comparison ref %q resolves to the target worktree branch and

Error message

comparison ref %q resolves to the target worktree branch and cannot independently prove containment

What it means

Even if a ref is valid and shared, if it names (or resolves to) the target worktree's own branch, it equals the HEAD being checked and cannot independently prove containment — an ancestor check of HEAD against itself is trivially self-referential — so bd rejects the selector.

Source

Thrown at cmd/bd/worktree_cmd.go:1881

	git *worktreeRemovalGit,
	executionRoot string,
	target pinnedWorktreeTarget,
	selector string,
	ref string,
	explicit bool,
) (pinnedWorktreeComparator, error) {
	terminalRef, err := resolveWorktreeTerminalRef(ctx, git, executionRoot, ref)
	if err != nil {
		return pinnedWorktreeComparator{}, err
	}
	if isWorktreeLocalRef(ref) || isWorktreeLocalRef(terminalRef) {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"comparison ref %q resolves through a worktree-local ref namespace and cannot independently prove containment",
			ref,
		)
	}
	if ref == target.branch || terminalRef == target.branch {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"comparison ref %q resolves to the target worktree branch and cannot independently prove containment",
			ref,
		)
	}
	oid, err := resolveWorktreeCommitOID(ctx, git, executionRoot, ref)
	if err != nil {
		return pinnedWorktreeComparator{}, fmt.Errorf("comparison ref %q does not resolve to a commit: %w", ref, err)
	}
	return pinnedWorktreeComparator{
		selector:    selector,
		explicit:    explicit,
		ref:         ref,
		terminalRef: terminalRef,
		oid:         oid,
	}, nil
}

func resolveWorktreeTerminalRef(

View on GitHub (pinned to 71377f2769)

Solutions

1. Pass the branch the worktree was merged INTO (e.g. `refs/heads/main`), not the worktree's own branch
2. Check the target branch name (shown by `bd worktree list`) and choose a different ref
3. Use a descendant commit OID on another branch that strictly contains the worktree HEAD

Example fix

// before (worktree's own branch)
bd worktree remove --merged-into refs/heads/feature-x
// after (the branch it was merged into)
bd worktree remove --merged-into refs/heads/main

// shell pre-check: selector must not be the target branch
branch=$(git -C "$WORKTREE" symbolic-ref --short HEAD)
[ "$SEL" != "$branch" ] || echo "selector equals the target worktree branch"

When it happens

Trigger: Passing `--merged-into <ref>` where `ref` equals `target.branch` or the ref's terminal resolution equals `target.branch`.

Common situations: Naming the branch checked out in the worktree being removed; a symbolic ref chain that ends at the target branch; scripting `--merged-into $(git symbolic-ref HEAD)` inside the target worktree.

Related errors

• comparison ref %q resolves through a worktree-local ref name
• --merged-into object ID %q is the target HEAD itself; use a
• not a git repository
• failed to install hooks: %w
• git config --unset core.hooksPath failed: %w (output: %s)

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/a0111a13492ffab7. Report an issue: GitHub.