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

[Julia Evans <julia@jvns.ca>]

On 2026-11-13 12:23 p.m., Junio C Hamano wrote:
> Julia Evans <julia@jvns.ca> writes:
>
>>> The mention of "your current work" (started at the HEAD) and "next
>>> commit" is to lay groundwork to explain what happens when they make
>>> that commit, and how it is different when they are on detached HEAD,
>>> in contrast to when they are on a branch.  After all, what we were
>>> discusssing is an improved explanation on detached HEAD, and your
>>> commits not affecting any of your branch *is* the most important
>>> aspect of what detached HEAD gives you
>> I read this a few times and it's hard for me to tell what the issue
>> being raised is.
>>
>> Are you saying that we're not explaining all the details from "`HEAD`
>> can store either a branch or commit ID" to "if you create new commits
>> while in detached HEAD state, those commits won't be on a branch"?
> No.  I do not expect an introductory document to tell *all* the
> things that needs to be known about a topic.  That is an
> encyclopedia, not a technical manual.
>
> The fact that you would not clobber any branches when you make a
> temporary commit on a detached HEAD, however, is the most important
> consequence of HEAD *not* recording what branch we are on that has
> real *impact* to the end-users.  They can leave their temporary work
> behind without explicit removal by just checking out a branch, which
> also means they have to be careful about losing *if* they care about
> what they did during this temporary state.
>
> I view it as a disservice to deliberately avoid talking about it.

Okay. How about this?  (the added sentence is between the **)

   For example, a data scientist could use this to run an old version of a
   data pipeline or a programmer could use this to figure out when a bug
   was introduced. **You can also use this to make experimental commits
   without being on a branch.** By detaching `HEAD`, you don't need to
   create a temporary branch.