gastownhall/beads · error

comparison ref %q does not resolve to a commit: %w

Error message

comparison ref %q does not resolve to a commit: %w

What it means

For an accepted comparison ref, bd resolves it to a commit OID via `resolveWorktreeCommitOID`. If resolution fails (unknown ref, non-commit object, git error), this wrapped error reports the ref name plus the underlying cause.

Source

Thrown at cmd/bd/worktree_cmd.go:1888

	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(
	ctx context.Context,
	git *worktreeRemovalGit,
	executionRoot string,
	ref string,
) (string, error) {
	current := ref
	seen := make(map[string]struct{})

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `git rev-parse <ref>^{commit}` to reproduce the underlying error
2. Verify the ref exists with `git show-ref | grep <ref>` and re-fetch if it is a remote ref (`git fetch origin`)
3. Use a concrete local branch (`refs/heads/...`) or a full commit OID instead
4. Check for broken symbolic refs with `git symbolic-ref <ref>` and repair

Example fix

// diagnose
git rev-parse origin/feature-x^{commit}
// fix stale remote ref
git fetch origin --prune
bd worktree remove --merged-into refs/heads/main

// shell pre-check
git rev-parse "$REF^{commit}" >/dev/null 2>&1 || echo "$REF does not resolve to a commit"

if err != nil && strings.Contains(err.Error(), "does not resolve to a commit") {
    // refresh refs (git fetch --prune) or switch to a full commit OID, then retry
}

When it happens

Trigger: `--merged-into <ref>` where the ref exists as a name pattern but `git rev-parse <ref>^{commit}` fails — dangling symbolic ref, ref pointing to a tree/blob/tag that cannot peel to a commit, or ref deleted between validation and resolution.

Common situations: Remote-tracking ref whose remote was pruned; annotated tag resolving unexpectedly in a shallow clone; race where the branch is deleted while the command runs; broken symref (`refs/heads/x` → deleted branch).

Related errors

• --merged-into value %q does not name an existing unambiguous
• --merged-into object ID %q does not resolve to a commit: %w
• --merged-into object ID %q is the target HEAD itself; use a
• auto-export: git add failed: %w
• failed to read .gitignore: %w

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