Skip to content

fix(worktree): enforce git >=2.42 floor and silence unborn-HEAD guard warning - #664

Closed
tarikcosovic97 wants to merge 1 commit into
andresharpe:releases/4.1.0from
tarikcosovic97:fix/worktree-setup-fails-659
Closed

fix(worktree): enforce git >=2.42 floor and silence unborn-HEAD guard warning#664
tarikcosovic97 wants to merge 1 commit into
andresharpe:releases/4.1.0from
tarikcosovic97:fix/worktree-setup-fails-659

Conversation

@tarikcosovic97

Copy link
Copy Markdown
Contributor

Linked issue

Closes #659

Summary of changes

Starting any workflow in a brand-new project (git init + dotbot init + workflow run) used to surface a scary ⚠ Branch guard warning: Cannot find base branch line on every Git version — and on Git <2.42 also crashed the very first worktree add with a cryptic fatal: invalid reference: task/… (because git worktree add --orphan didn't exist yet, and the fallback tried to attach to a branch that wasn't there).

This PR takes the version-floor path discussed on the ticket rather than auto-creating an empty initial commit:

  • Enforce Git ≥ 2.42 as the operating floor. New helpers in Dotbot.Workflow (ConvertTo-DotbotGitVersion, Get-DotbotGitVersion, Get-MinDotbotGitVersion) parse the installed git version and drive a new git_too_old refusal in Test-GitReadyForWorktree. The same check is mirrored inline in _Test-GitReadyForWorktree under Dotbot.Worktree/Private/ to keep that module's zero-dep contract. Users on older Git now get a single clear message telling them what to upgrade to instead of a downstream crash.
  • Silence the unborn-HEAD warning. Assert-OnBaseBranch now returns $null early when Test-RepositoryHasCommits is false, since there's genuinely no base branch to switch to yet — the first task creates one via its orphan-worktree squash-merge. Removes the misleading Branch guard warning: Cannot find base branch that fired on every fresh-project workflow run, on every Git version.
  • README bumped: prerequisite is now Git 2.42+, with a short reason.

Together these turn the "no commits yet" first-run flow from noisy-and-broken (on old Git) or noisy-but-works (on new Git) into quiet and correct on any supported Git.

Screenshots / recordings

N/A — CLI-only behaviour change.

Testing notes

New assertions land in the existing suites:

  • tests/Test-Worktree.ps1 — new "Assert-OnBaseBranch — unborn repo" section: does not throw, returns $null, does not create a commit. 80/80 pass.
  • tests/Test-WorkflowManifest.ps1 — new "Git version parsing" section: parser handles standard/two-component/legacy-windows/empty/garbage input; Get-MinDotbotGitVersion returns 2.42.0; version comparison confirms 2.31 < floor and 2.42 = floor; Get-DotbotGitVersion returns a System.Version when git is on PATH. 558/558 pass.

Adjacent suites re-run to confirm no regression:

  • tests/Test-Runtime.ps1 — 100/100 pass (1 skip)
  • tests/Test-WorkflowIntegration.ps1 — 143/143 pass

Total: 881/881 pass, 0 fail.

Manual verify (Git 2.53 host): the direct Assert-OnBaseBranch call on a fresh git init unborn repo now returns silently instead of throwing Cannot find base branch. The git_too_old refusal path is straight-line code from the pure-function tests above; it can't naturally reproduce on a modern host.

Checklist

  • Tests added or updated
  • Docs updated (if behaviour changed)
  • Linked issue exists
  • Follows the contribution guide

… warning

Fresh `git init` + `dotbot init` + workflow run used to produce a scary
"Branch guard warning: Cannot find base branch" line on every Git version,
and on Git <2.42 also failed the first worktree add with a cryptic
`fatal: invalid reference` (because `worktree add --orphan` didn't exist
yet and the fallback tries to attach to a branch that isn't there).

Enforce Git 2.42 as the operating floor in `Test-GitReadyForWorktree`
(and its private twin) with a new `git_too_old` refusal, and make
`Assert-OnBaseBranch` silently no-op on an unborn HEAD so the first-run
flow is quiet instead of misleading.

Closes andresharpe#659

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@tarikcosovic97

Copy link
Copy Markdown
Contributor Author

@aselim31 ready for review.

@carlospedreira

Copy link
Copy Markdown
Collaborator

@tarikcosoviciwgplc We cannot enforce Git 2.42+. Ubuntu 22.04 is still supported through May 2027 and ships Git 2.34.1. Enforcing 2.42 would immediately break supported default installations, so this change is not acceptable. The implementation must retain compatibility with Git 2.34.1 rather than raising the minimum version.

@tarikcosovic97

Copy link
Copy Markdown
Contributor Author

@carlospedreira

Here is the new PR for this using the preferred approach #675

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants