CODEWITHSUNDEEP
git
SoniEx2
SoniEx2

Reputation: 2044

Where is "HEAD" defined as not a valid branch name?

I'm looking at git docs, but nowhere does it say "HEAD" is an invalid branch name. Yet, trying to make a branch called "HEAD" gives me:

fatal: 'HEAD' is not a valid branch name.

If this is documented anywhere, I'm not seeing it. As far as the documentation is concerned, I should be able to do this? But why can't I?

Upvotes: 5

Views: 4422

Answers (1)

torek
torek

Reputation: 489888

The name HEAD (in all capitals) is special and precious in Git. If the special HEAD file, .git/HEAD, goes missing, Git stops believing that the repository is a repository.

The git check-ref-format documentation should note that HEAD is not a valid name here, but fails to do so. (It does note that @, a synonym for HEAD, is reserved.)

Note that head (lowercase) is allowed as a branch name—but if you are on Windows or MacOS, don't use it!1 It will act weird, due to the resolution order as noted in the gitrevisions documentation, where the file system will allow Git to open the special HEAD file under the name head.

Technically, this caveat applies anywhere you have a case-insensitive file system. You can have one on Linux, and you can make case-sensitive file systems on MacOS.

Upvotes: 11

Related Questions