gastownhall/beads · error

target HEAD does not resolve to a commit

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.

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 common git directory
• failed to resolve target git directory
• git returned invalid commit object ID
• cannot remove a worktree when the primary worktree is bare
• cannot remove the primary worktree

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

Appendix: 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)