threads / bug / 66239

[Bug] Porcelain allows creation of '@' branch

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

## tl;dr

The report turned into a debate over whether the '@' shorthand is a good design, with Junio Hamano arguing it should not block valid ref names. Read the story.

replies: 15people: 5as markdown or json

Bence Csókás· Aug 31, 2026, 14:22 UTC · lore
Hi,

I ran into this issue a few weeks ago. I'm using Git 2.55.0, which is the latest released.

`git help check-ref-format` says this about a branch name:
   [...]
   9. They cannot be the single character @.
   [...]
And as expected, it is rejected:
   $ git check-ref-format @ && echo BUG!
   $
However, the following commands all create a branch named @ :
   $ git checkout -b @
   $ git switch -c @
   $ git branch @

I believe this to be a bug. Other invalid names are properly rejected though:

   $ git checkout -b master@{1}
   fatal: 'master@{1}' is not a valid branch name
   hint: See 'git help check-ref-format'
   hint: Disable this message with "git config set advice.refSyntax false"
   $ git checkout -b @{1}
   fatal: '@{1}' is not a valid branch name
   hint: See 'git help check-ref-format'
   hint: Disable this message with "git config set advice.refSyntax false"
   $ git checkout -b @^
   fatal: '@^' is not a valid branch name
   hint: See 'git help check-ref-format'
   hint: Disable this message with "git config set advice.refSyntax false"

After creation, this branch cannot be checked out again, as `git checkout @` is a no-op. Luckily though, `git branch -d @` works, so I didn't permanently damage my Git repo :P

Bence

P.S. as I was typing this mail, I realized that I should've given `--branch` to check-ref-format, and sure enough, there's the problem:

   $ git check-ref-format --branch @
   @
   $ git check-ref-format --branch @{1}
   fatal: '@{1}' is not a valid branch name
   $

Not sure why it thinks that would be a valid branch name... IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

D. Ben Knoble· Aug 31, 2026, 19:59 UTC · re: Bence Csókás · lore

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

On Mon, Aug 31, 2026 at 3:12 PM Bence Csókás <bence.csokas@arm.com> wrote:
Show 11 quoted lines
>
> Hi,
>
> I ran into this issue a few weeks ago. I'm using Git 2.55.0, which is
> the latest released.
>
> `git help check-ref-format` says this about a branch name:
>
>    [...]
>    9. They cannot be the single character @.
>    [...]
This is the rule for a reference.
Show 10 quoted lines
> And as expected, it is rejected:
>
>    $ git check-ref-format @ && echo BUG!
>    $
>
> However, the following commands all create a branch named @ :
>
>    $ git checkout -b @
>    $ git switch -c @
>    $ git branch @
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?

Show 33 quoted lines
> I believe this to be a bug. Other invalid names are properly rejected
> though:
>
>    $ git checkout -b master@{1}
>    fatal: 'master@{1}' is not a valid branch name
>    hint: See 'git help check-ref-format'
>    hint: Disable this message with "git config set advice.refSyntax false"
>    $ git checkout -b @{1}
>    fatal: '@{1}' is not a valid branch name
>    hint: See 'git help check-ref-format'
>    hint: Disable this message with "git config set advice.refSyntax false"
>    $ git checkout -b @^
>    fatal: '@^' is not a valid branch name
>    hint: See 'git help check-ref-format'
>    hint: Disable this message with "git config set advice.refSyntax false"
>
> After creation, this branch cannot be checked out again, as `git
> checkout @` is a no-op. Luckily though, `git branch -d @` works, so I
> didn't permanently damage my Git repo :P
>
> Bence
>
> P.S. as I was typing this mail, I realized that I should've given
> `--branch` to check-ref-format, and sure enough, there's the problem:
>
>    $ git check-ref-format --branch @
>    @
>    $ git check-ref-format --branch @{1}
>    fatal: '@{1}' is not a valid branch name
>    $
>
> Not sure why it thinks that would be a valid branch name...
> IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
(I don't recall offhand where we describe valid branch names, if at all.)
-- 
D. Ben Knoble
Jeff King· Sep 2, 2026, 07:37 UTC · re: D. Ben Knoble · lore

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

On Mon, Aug 31, 2026 at 03:59:56PM -0400, D. Ben Knoble wrote:
Show 11 quoted lines
> 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
Kristoffer Haugsbakk· Sep 3, 2026, 08:38 UTC · re: D. Ben Knoble · lore

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

On Mon, Aug 31, 2026, at 21:59, D. Ben Knoble wrote:
Show 37 quoted lines
> On Mon, Aug 31, 2026 at 3:12 PM Bence Csókás <bence.csokas@arm.com> wrote:
>>
>> Hi,
>>
>> I ran into this issue a few weeks ago. I'm using Git 2.55.0, which is
>> the latest released.
>>
>> `git help check-ref-format` says this about a branch name:
>>
>>    [...]
>>    9. They cannot be the single character @.
>>    [...]
>
> This is the rule for a reference.
>
>> And as expected, it is rejected:
>>
>>    $ git check-ref-format @ && echo BUG!
>>    $
>>
>> However, the following commands all create a branch named @ :
>>
>>    $ git checkout -b @
>>    $ git switch -c @
>>    $ git branch @
>
> 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?
Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
    I suspect that it is much more productive to deprecate and remove
    "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
    does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
>[snip]
Bence Csókás· Sep 3, 2026, 12:35 UTC · re: Kristoffer Haugsbakk · lore

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

On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
Show 5 quoted lines
> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>
>      I suspect that it is much more productive to deprecate and remove
>      "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>      does not act as a synonym for "refs/remotes/origin/HEAD"). [...]

I would not want to see @ removed, I have abandoned using HEAD years ago, too much typing (especially if you want to express more complex things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to pick an example out of my bash-history).

Bence IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Ben Knoble· Sep 3, 2026, 15:14 UTC · re: Bence Csókás · lore

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

Show 12 quoted lines
> Le 3 sept. 2026 à 08:36, Bence Csókás <bence.csokas@arm.com> a écrit :
> 
> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>> 
>>     I suspect that it is much more productive to deprecate and remove
>>     "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>>     does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
> I would not want to see @ removed, I have abandoned using HEAD years
> ago, too much typing (especially if you want to express more complex
> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
> pick an example out of my bash-history).
Ditto, though thanks for digging up the reference. It will surely be important to justify when proposing to tighten the branch-mode rules. 
Junio C Hamano· Sep 3, 2026, 18:45 UTC · re: Ben Knoble · lore

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

Ben Knoble <ben.knoble@gmail.com> writes:
Show 14 quoted lines
>> Le 3 sept. 2026 à 08:36, Bence Csókás <bence.csokas@arm.com> a écrit :
>> 
>> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
>>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>>> 
>>>     I suspect that it is much more productive to deprecate and remove
>>>     "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>>>     does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
>> I would not want to see @ removed, I have abandoned using HEAD years
>> ago, too much typing (especially if you want to express more complex
>> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
>> pick an example out of my bash-history).
>
> Ditto, though thanks for digging up the reference. It will surely be important to justify when proposing to tighten the branch-mode rules. 

It is very unfortunate that the quote is partial and incomplete, though, and would not be a good input for people to decide on their own.

Kristoffer Haugsbakk· Sep 6, 2026, 07:56 UTC · re: Junio C Hamano · lore

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

On Thu, Sep 3, 2026, at 20:45, Junio C Hamano wrote:
Show 20 quoted lines
> Ben Knoble <ben.knoble@gmail.com> writes:
>
>>> Le 3 sept. 2026 à 08:36, Bence Csókás <bence.csokas@arm.com> a écrit :
>>>
>>> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
>>>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>>>>
>>>>     I suspect that it is much more productive to deprecate and remove
>>>>     "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>>>>     does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
>>> I would not want to see @ removed, I have abandoned using HEAD years
>>> ago, too much typing (especially if you want to express more complex
>>> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
>>> pick an example out of my bash-history).
>>
>> Ditto, though thanks for digging up the reference. It will surely be important to justify when proposing to tighten the branch-mode rules.
>
> It is very unfortunate that the quote is partial and incomplete,
> though, and would not be a good input for people to decide on their
> own.

Sorry that I misrepresented your post. The gist to me was that you weren’t interested in more code to deal with the `@` shorthand.

Bence Csókás· Oct 15, 2026, 07:58 UTC · re: Bence Csókás · lore

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

On 2026. 09. 03. 14:35, Bence Csókás wrote:
Show 12 quoted lines
> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>>
>>      I suspect that it is much more productive to deprecate and remove
>>      "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>>      does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
> I would not want to see @ removed, I have abandoned using HEAD years
> ago, too much typing (especially if you want to express more complex
> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
> pick an example out of my bash-history).
>
> Bence
P.S.:

$ history | grep 'git .*@' | wc -l 74 $ history | grep HEAD | wc -l 0

;)

Bence IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Junio C Hamano· Oct 16, 2026, 15:35 UTC · re: Bence Csókás · lore

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

Bence Csókás <bence.csokas@arm.com> writes:
Show 22 quoted lines
> On 2026. 09. 03. 14:35, Bence Csókás wrote:
>> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
>>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
>>>
>>>      I suspect that it is much more productive to deprecate and remove
>>>      "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
>>>      does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
>> I would not want to see @ removed, I have abandoned using HEAD years
>> ago, too much typing (especially if you want to express more complex
>> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
>> pick an example out of my bash-history).
>>
>> Bence
>
> P.S.:
>
> $  history | grep 'git .*@' | wc -l
> 74
> $  history | grep HEAD | wc -l
> 0
>
> ;)
You have some unlearning of a bad habit to do, then ;-)
D. Ben Knoble· Oct 16, 2026, 18:09 UTC · re: Junio C Hamano · lore

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

On Fri, Oct 16, 2026 at 11:35 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 27 quoted lines
>
> Bence Csókás <bence.csokas@arm.com> writes:
>
> > On 2026. 09. 03. 14:35, Bence Csókás wrote:
> >> On 2026. 09. 03. 10:38, Kristoffer Haugsbakk wrote:
> >>> Not a bug (2024) https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
> >>>
> >>>      I suspect that it is much more productive to deprecate and remove
> >>>      "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
> >>>      does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
> >> I would not want to see @ removed, I have abandoned using HEAD years
> >> ago, too much typing (especially if you want to express more complex
> >> things, e.g. `git range-diff long-branch-name{^..otherbranch,..@}`, to
> >> pick an example out of my bash-history).
> >>
> >> Bence
> >
> > P.S.:
> >
> > $  history | grep 'git .*@' | wc -l
> > 74
> > $  history | grep HEAD | wc -l
> > 0
> >
> > ;)
>
> You have some unlearning of a bad habit to do, then ;-)

Phaw! What's good (short and easy to type) for interactive use may not be great for scripts, sure, (in which case spelling out long options, writing HEAD, etc., is advisable).

But shorthands are convenient day-to-day. What's a bad habit about that?

(Besides, the OP's grep also counts uses of @{upstream}/@{u}/@{push}/reflog syntax/etc.)

-- 
D. Ben Knoble
Kristoffer Haugsbakk· Oct 16, 2026, 18:21 UTC · re: D. Ben Knoble · lore

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

On Fri, Oct 16, 2026, at 20:09, D. Ben Knoble wrote:
Show 27 quoted lines
> On Fri, Oct 16, 2026 at 11:35 AM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Bence Csókás <bence.csokas@arm.com> writes:
>>
>> > On 2026. 09. 03. 14:35, Bence Csókás wrote:
>>>>>[snip]
>> >> Bence
>> >
>> > P.S.:
>> >
>> > $  history | grep 'git .*@' | wc -l
>> > 74
>> > $  history | grep HEAD | wc -l
>> > 0
>> >
>> > ;)
>>
>> You have some unlearning of a bad habit to do, then ;-)
>
> Phaw! What's good (short and easy to type) for interactive use may not
> be great for scripts, sure, (in which case spelling out long options,
> writing HEAD, etc., is advisable).
>
> But shorthands are convenient day-to-day. What's a bad habit about that?
>
> (Besides, the OP's grep also counts uses of
> @{upstream}/@{u}/@{push}/reflog syntax/etc.)

I set up `git symbolic-ref refs/H HEAD` after my first `@` conversation.[1]

🔗 1: https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/
Junio C Hamano· Oct 16, 2026, 18:52 UTC · re: Kristoffer Haugsbakk · lore

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

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 5 quoted lines
>> (Besides, the OP's grep also counts uses of
>> @{upstream}/@{u}/@{push}/reflog syntax/etc.)
>
> I set up `git symbolic-ref refs/H HEAD` after my first `@`
> conversation.[1]

That is funny and clever, but unfortunately it does not help solving the problem that the @-shorthand "conveniently" squats there to make your use of a branch named "@" hard or impossible.

Kristoffer Haugsbakk· Oct 17, 2026, 16:43 UTC · re: Junio C Hamano · lore

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

On Fri, Oct 16, 2026, at 20:52, Junio C Hamano wrote:
Show 11 quoted lines
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>>> (Besides, the OP's grep also counts uses of
>>> @{upstream}/@{u}/@{push}/reflog syntax/etc.)
>>
>> I set up `git symbolic-ref refs/H HEAD` after my first `@`
>> conversation.[1]
>
> That is funny and clever, but unfortunately it does not help solving
> the problem that the @-shorthand "conveniently" squats there to make
> your use of a branch named "@" hard or impossible.

It replaces my want to use `@` which means that what you wrote back then:[1]

JCH> I suspect that it is much more productive to deprecate and remove JCH> "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@" JCH> does not act as a synonym for "refs/remotes/origin/HEAD"). [...]

Would not affect me. (Not that I believe that it would happen.)
[1]: https://lore.kernel.org/git/xmqqy12z7eti.fsf@gitster.g/#t
Junio C Hamano· Oct 17, 2026, 16:59 UTC · re: Kristoffer Haugsbakk · lore

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

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 8 quoted lines
> It replaces my want to use `@` which means that what you wrote
> back then:[1]
>
> JCH> I suspect that it is much more productive to deprecate and remove
> JCH> "@" that is a built-in synomym for HEAD (but "refs/remotes/origin/@"
> JCH> does not act as a synonym for "refs/remotes/origin/HEAD"). [...]
>
> Would not affect me. (Not that I believe that it would happen.)

I do not think it would happen, either. There are many things in Git that I have publicly said are poorly designed, but that we cannot correct due to heavy inertia.

Junio C Hamano· Oct 16, 2026, 18:40 UTC · re: D. Ben Knoble · lore

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

"D. Ben Knoble" <ben.knoble@gmail.com> writes:
> But shorthands are convenient day-to-day. What's a bad habit about that?

A shorthand may be convenient, but not all "convenient" things are automatically good. A poorly designed, ill-thought-out shorthand that forbids a branch whose name follows a set of clearly defined rules perfectly well is good example.

← back to recent threads