Re: [Bug] Porcelain allows creation of '@' branch

[Jeff King <peff@peff.net>]

On Mon, Aug 31, 2026 at 03:59:56PM -0400, D. Ben Knoble wrote:

> But (with git refs list) we should see this creates a ref "refs/heads/@".
> 
> I happen to think that's extremely confusing given that "@" is the
> shorthand for HEAD, but… it's not against the current documented
> rules, I think. (e.g., "git switch @" will fail, since it sees "git
> switch HEAD"; using "refs/heads/@" will also fail.) git-checkout
> doesn't fail but also doesn't change to the "@" branch. Futzing with
> .git/HEAD and restoring the working tree works, but… yikes.
> 
> Of course, --branch mode is allowed to be stricter; maybe we should
> reject this case?

Yeah, sadly bare "@" is allowed in a component (but not "@{") because
we've maintained strict backwards compatibility. So I don't think it's a
_bug_ exactly, but in the past we have restricted the porcelain
interfaces (so git-branch, but not git-update-ref) to avoid such
footguns. The most notable one is HEAD:

  $ git check-ref-format refs/heads/HEAD; echo $?
  0

  $ git check-ref-format --branch HEAD; echo $?
  fatal: 'HEAD' is not a valid branch name
  128

which also shows off that "--branch" is a convenience option for using
those stricter porcelain rules.

I think it would make sense to treat bare "@" the same as HEAD here. We
probably _don't_ want to forbid any "@", though. Branches and tags like
foo@bar are legal (if IMHO somewhat gross), and less likely to be used
accidentally.

So I think there is no bug, in the sense that the system is working as
designed, but it sure would be a nice feature to block this footgun.

> (I don't recall offhand where we describe valid branch names, if at all.)

I don't think we document the magic porcelain-tightening rules anywhere.
That's probably OK in practice; the point of "check-ref-format --branch"
is to check against them programatically.

-Peff