Worktree setup fails on empty repo (unborn HEAD) — no actionable error, no auto-fix

[aselim31]

Problem Statement

An empty folder is the most natural starting point when using dotbot to scaffold a new project. But if the folder has been git init-ed with no commits yet, dotbot crashes immediately with a cryptic git error and no recovery path. The user has to know — unprompted — to create a manual initial commit before running any workflow. This happens on every new project, the error message gives no hint about the cause, and the workaround is not surfaced anywhere in the CLI output.

How to Reproduce

mkdir my-new-project && cd my-new-project
git init                 # creates unborn HEAD on 'master', no commits
dotbot init              # seeds .bot/workspace + .gitignore
# start any workflow (e.g. azure-to-github) and run the first task

Observe:

⚠ Branch guard warning: Cannot find base branch in C:\code\my-new-project
✗ Task failed unexpectedly: Worktree setup failed for task 'Fetch Work Item':
    Failed to create worktree: git worktree add failed:
    fatal: invalid reference: task/t_mvsYTO-fetch-work-item
✗ Mandatory task failed: Fetch Work Item - stopping workflow

There is no mention of "no commits" or what to do next.

Original Report

Summary

Starting any workflow in a brand-new dotbot project fails on the very first task. If the project's git repo has been git init'd but has no commits yet (unborn HEAD), worktree creation aborts with a cryptic git error and the workflow stops immediately.

Since v4 removed skip_worktree and every task now runs in a git worktree, this blocks the first run of a fresh project entirely — there is no longer a non-worktree path that would have sidestepped it.

Environment

dotbot version	4.0.0
Platform	Windows 11
git	2.31.1.windows.1
Project repo	freshly git init'd, default branch master, 0 commits

Root Cause

In src/runtime/Modules/Dotbot.Worktree/Dotbot.Worktree.psm1, Resolve-DotbotBaseBranch uses git rev-parse --verify to confirm a branch exists. On an unborn repo, master is a symbolic ref with no commit — rev-parse --verify fails, the function returns $null, and Assert-OnBaseBranch throws "Cannot find base branch".

The module already has Test-RepositoryHasCommits and Resolve-UnbornBaseBranch helpers for this exact case, but they are never called from the worktree-creation path. The fix is already half-written but not wired in.

Preferred fix

When Test-RepositoryHasCommits returns $false, auto-create an empty initial commit before the first git worktree add:

git commit --allow-empty -m "chore: initial commit"

This makes git init + dotbot init + dotbot workflow run work end-to-end with no manual steps.

Minimum fix

If auto-commit is not acceptable, fail fast with a clear message and the exact command to run — not the current cryptic Cannot find base branch / fatal: invalid reference chain.

Workaround (current)

git add -A && git commit -m "chore: initial commit"
# or
git commit --allow-empty -m "init"

Note

Supersedes #513 — original was closed with the workaround above documented in a comment, but no code was changed. Confirmed recurring across multiple users on every new project start.

[tarikcosovic97]

Feel free to assign this one to me @aselim31

[tarikcosovic97]

It seems that the underlying issue happens due to an older git version.

My Git is 2.53 — git worktree add --orphan was added in Git 2.42, so the fallback path in New-TaskWorktree Dotbot.Worktree.psm1:1481 actually works for me.

The reporter's Git 2.31.1 doesn't have --orphan, so it hits fatal: invalid reference.

Do we want to go with the preferred fix as described on the ticket, making an empty commit beforehand which would add a fallback to versions lower than 2.42 or perhaps we'd want to ensure the minimal required version of git is 2.42 moving forward, because I am pretty sure we will use some more features that don't exist in the older versions and moving forward we'd want to avoid fallbacks/workarounds in that case.

@aselim31 has already agreed that we move the min required version to 2.42, @aldinhasanspahic-api tagging you for visibility and validation from your end.

[tarikcosovic97]

The PR for this ticket is ready and available at - #664

[aselim31]

@tarikcosovic97 I dont see a PR here , so no fix needed here as per previous discussion ?