gastownhall/beads · error

target HEAD does not resolve to a commit: %w

Error message

target HEAD does not resolve to a commit: %w

What it means

inspectWorktreeTarget verifies the worktree's HEAD resolves to a commit via `git rev-parse --verify --quiet HEAD^{commit}`. When HEAD is unborn, corrupt, or unresolvable, this error is thrown before any destructive removal proceeds.

Source

Thrown at cmd/bd/worktree_cmd.go:980

		worktree.path,
		"rev-parse",
		"--path-format=absolute",
		"--git-common-dir",
	)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("failed to resolve target common git directory: %w", err)
	}
	headOutput, err := git.output(
		ctx,
		worktree.path,
		"rev-parse",
		"--verify",
		"--quiet",
		"--end-of-options",
		"HEAD^{commit}",
	)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("target HEAD does not resolve to a commit: %w", err)
	}
	statusOutput, err := git.output(
		ctx,
		worktree.path,
		"status",
		"--porcelain=v1",
		"-z",
		"--untracked-files=all",
		"--ignore-submodules=none",
		"--ignored=matching",
	)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("failed to inspect target cleanliness: %w", err)
	}

	headOID := strings.TrimSpace(string(headOutput))
	if headOID == "" || headOID != worktree.headOID {
		return pinnedWorktreeTarget{}, fmt.Errorf(

View on GitHub (pinned to 71377f2769)

Solutions

1. Make at least one commit in the worktree or check out an existing branch so HEAD resolves, then retry removal.
2. Run `git -C <path> rev-parse HEAD^{commit}` to reproduce and inspect the raw error.
3. If objects are missing, re-fetch (`git fetch --unshallow` or fetch from origin) to restore them.
4. If the worktree is disposable, prune it (`git worktree prune`), remove the directory, and clean the registry.

Example fix

// before
bd worktree remove feature-x
// error: target HEAD does not resolve to a commit (unborn branch)
// after
cd /repo/.worktrees/feature-x && git switch main
bd worktree remove feature-x

const probe = Bun.spawnSync(["git", "-C", worktreePath, "rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
if (probe.exitCode !== 0) {
  throw new Error(`HEAD unresolvable (unborn branch or corrupt objects): ${worktreePath}`);
}

try {
  await bd("worktree", "remove", path);
} catch (e) {
  if (String(e.message).includes("does not resolve to a commit")) {
    execSync(`git -C ${path} switch main`);
  } else throw e;
}

When it happens

Trigger: Removing a worktree on an unborn branch (fresh `git worktree add` with a new branch and no commits); HEAD file corrupted; the referenced commit is missing from the object database (shallow/partial clone corruption, gc removed objects); git command failure.

Common situations: Worktree created from a brand-new branch never committed to; interrupted clone/checkout left objects missing; aggressive `git gc` or filesystem corruption removed objects; shallow fetch setups.

Related errors

• failed to resolve target git directory: %w
• failed to resolve target common git directory: %w
• git returned invalid commit object ID %q
• git rev-parse timed out after %s
• failed to inspect created worktree cleanliness: %w %s

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