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

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

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.