gastownhall/beads · error

failed to resolve target common git directory: %w

Error message

failed to resolve target common git directory: %w

What it means

After resolving the per-worktree git dir, inspectWorktreeTarget runs `git rev-parse --path-format=absolute --git-common-dir` to find the repository's shared common git directory. Failure is wrapped in this error: git could not identify the shared objects/refs directory backing the worktree.

Source

Thrown at cmd/bd/worktree_cmd.go:968

func inspectWorktreeTarget(
	ctx context.Context,
	git *worktreeRemovalGit,
	worktree registeredWorktree,
) (pinnedWorktreeTarget, error) {
	gitDirOutput, err := git.output(ctx, worktree.path, "rev-parse", "--absolute-git-dir")
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("failed to resolve target git directory: %w", err)
	}
	gitDir := filepath.Clean(strings.TrimSpace(string(gitDirOutput)))
	commonDirOutput, err := git.output(
		ctx,
		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",

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped git error; reproduce with `git -C <path> rev-parse --git-common-dir`.
2. Verify the main repository still exists at the location in the worktree's .git file; restore or re-clone it if moved.
3. Recreate the broken worktree: `git worktree remove --force <path>` (or prune) then `git worktree add` again.
4. Upgrade git to >= 2.31 if the flag itself is unsupported.

Example fix

// before
bd worktree remove feature-x
// error: failed to resolve target common git directory: ... (main .git moved)
// after
git worktree prune
rm -rf /repo/.worktrees/feature-x
git worktree add /repo/.worktrees/feature-x main

const probe = Bun.spawnSync(["git", "-C", worktreePath, "rev-parse", "--git-common-dir"]);
if (probe.exitCode !== 0) {
  throw new Error("common dir unresolvable; main repo missing or moved");
}

try {
  await bd("worktree", "remove", path);
} catch (e) {
  if (String(e.message).includes("failed to resolve target common git directory")) {
    execSync(`git worktree prune && git worktree add ${path} main`);
  } else throw e;
}

When it happens

Trigger: The worktree's linkage to its parent repository is broken (dangling gitdir pointer, moved or deleted main repo .git), or the git subprocess fails or is canceled; also git too old to support --path-format=absolute.

Common situations: The main repository was moved, renamed, or deleted after worktree creation; a worktree copied to another machine without its main repo; git < 2.31; context timeout during removal.

Related errors

• failed to resolve target git directory: %w
• target HEAD does not resolve to a commit: %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/466c1c80c01cb85a. Report an issue: GitHub.