Show 28 quoted lines
> 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.
Sorry for the many replies.
I think I've realized that the real conflict here is that we're trying to write to two very different audiences:
1. Someone who's gotten into detached HEAD state by accident (maybe by running `git checkout <tag>`), is stressed, and just wants to understand what happened and what they should do. This is who I originally had in mind when I wrote the document.
2. A more advanced user who's curious about using detached HEAD state and wants to learn more about what they can do with it and what the implications are.
Of course these are both important audiences, but it's always hard to write a document for two very different audience at the same time. For example, one thing that came up in this thread is that creating commits while not on a branch is a problem for the first person and a good thing for the second person.
It could make sense to restructure it into two parts in the future (one along the lines of "help! get me out!" and one more like "here's a useful tool"), but this thread has already gone on for a long time and I'm not sure that would be productive at this point. It might help to add a note in the commit message saying that this "two audiences" situation is an issue with the current state and suggesting that perhaps it could be restructured in the future.