Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Nov 10, 2026, 06:46 UTC
- Message-ID
- <xmqqfqx9uqsn.fsf@gitster.g>
- In-Reply-To
- <f7d4600b-909f-4dd7-94da-d525649a9546@app.fastmail.com>
"Julia Evans" <julia@jvns.ca> writes:
Show 12 quoted lines
> 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.