Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

> On Sat, Nov 7, 2026, at 11:25 PM, Junio C Hamano wrote:
>> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>>
>>> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:
>>> +
>>> +1. A branch, which is your current branch.
>>> +2. A commit ID, when you don't have a current branch.
>>> +   This is called "detached HEAD state".
> ...
> Saying "it's a commit ID" is a simple way to say that it directly refers
> to a commit in a small number of words. I'm not sure what your goal is
> here, do you think that statement is somehow misleading to users?

Yes, I find it highly misleading, and otherwise I wouldn't be
discussing this patch.

I think the part I find it problematic the most in

    HEAD is a branch vs HEAD is a commit ID

is that HEAD *IS NOT* either of these things.  HEAD may record one
of these kinds of things but it never is a branch or an commit
object name.

And HEAD records one of these kinds of things to either directly or
indirectly refer to a commit that is currently checked out.

That is why I want to see the first description of the above to
serve as a solid base to convey these points, with later
descriptions we build on top:

 * `HEAD` can record either (1) a branch, or (2) a commit object
    name.

 * The purpose of HEAD doing so is to refer to a commit that is
   currently checked out, either directly or indirectly.

 * The latter (i.e., the direct reference) may be unfamiliar to
   users.  It is called "detached HEAD" state.

 * The commit referred to by the HEAD will become the parent of the
   commit you create.  When your HEAD records a branch, its tip is
   advanced.  Otherwise no branch is affected.  Either case, HEAD
   now refers to the commit you newly created.

And I find that saying "HEAD is a branch" or "HEAD is a commit" is
misleading and does not help that goal.

HTH.