Alias and hook templates render `{{ branch }}` as `HEAD` in a detached worktree

[max-sixty]

In a detached worktree, alias and hook templates render {{ branch }} as the literal HEAD. wt list --json reports branch: null for the same worktree, and the hook docs say an undefined variable errors so a template can guard it with a conditional. HEAD does neither: it is a string that git happily resolves as a ref, so every guard written around branch passes and the command runs against the wrong thing.

What I hit, with wt v0.76.0. An alias tidies a merged feature worktree and deletes its remote branch:

[aliases]
landed = 'git merge {{ default_branch }} --no-edit{% if branch != default_branch %} && git rev-parse --verify -q {{ remote }}/{{ branch }} >/dev/null && git push {{ remote }} --delete {{ branch }}{% endif %}'

Run from a worktree created with git worktree add --detach ../repo.scratch origin/main, branch renders as HEAD, so branch != default_branch passes; origin/HEAD is a symbolic ref in any ordinary clone, so the existence check passes too; and the alias ends with:

git push origin --delete HEAD
error: unable to delete 'HEAD': remote ref does not exist

Smallest repro:

[aliases]
probe = 'echo "[{{ branch }}]"'

git worktree add --detach ../repo.scratch origin/main
cd ../repo.scratch
wt -v probe

-v prints branch = HEAD in the template-variables block and the alias echoes [HEAD].

The fallback is deliberate: CommandContext::branch_or_head substitutes HEAD when there is no branch, and the hook pipeline matches it. Expected instead is one of:

• Leave branch unset in a detached worktree, so {% if branch %} guards it the way the docs already prescribe for upstream, and it agrees with the JSON output. This is the one I would pick.
• Or expose a detached variable alongside it.

The workaround today is {% if branch != "HEAD" %}, which holds only because git refuses HEAD as a branch name, and nothing documents that HEAD is what a detached worktree renders.

Seen on worktrunk bc2ec12.

This was written by Claude Code on behalf of max-sixty

[worktrunk-bot]

Reproduced and fixed in #4010, taking the first option — branch is simply absent in a detached worktree, so {% if branch %} guards it like upstream, and an unguarded {{ branch }} errors with the template named.

Three things beyond the one-line change, worth a look before merging:

• base and target for a manual wt hook <type> are derived from the current branch, so they follow it and stay unset too. The directional path vars keep working — the worktree exists whether or not it's on a branch.
• vars is now injected as the empty map rather than skipped when branch is absent, so {{ vars.key | default('x') }} still renders instead of erroring on an undefined vars under SemiStrict. Detached worktrees have no per-branch vars either way — wt config state vars set goes through require_current_branch — so nothing is lost.
• Two tests pinned the old fallback deliberately, and both are now failures for anyone relying on it: wt step for-each -- echo '{{ branch }}' stops at the detached worktree instead of printing HEAD (the same way {{ upstream }} already stops at the first non-tracking worktree), and a project pre-remove hook with an unguarded {{ branch }} blocks wt remove on a detached worktree until it's guarded. Both are the intended "fail rather than run against the wrong thing", but they're the shapes existing configs will hit.

The docs now say branch is unset in a detached worktree in the variable table, and connect it to wt list --format=json's branch: null in the undefined-variables section.