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

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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>     This is a pretty quick rewrite where we didn't get any user feedback. If
>     we really want to make sure it's clear to users as possible, we should
>     IMO do a second stage later where we ask users which parts are unclear.

OK.

>      * It's probably possible to explain HEAD better. That seems like a big
>        project to me since HEAD in Git is a very tricky topic. I think it
>        would be better to address in a separate patch series to have more
>        time to think it through. Or if we think it's not possible to merge
>        this without explaining HEAD better then I guess it shouldn't be
>        merged.

I do not understand why you need to draw a "take it or leave it"
with this topic here.  If you feel that the explanation of HEAD is
iffy, you know what we have here will not be the final version, and
you think we lack the capacity to reach the best possible
description with the usual review exchange, then I do not see why
you have to insist keeping what you initially have written.  You can
replace it with anything that is better than your initial version
and then still record that we will further polish it later in the
proposed log message and we will be in a better place, no?

Just to leave a record, so that we have better chance remembering
the suggested improved text, here are what I think the first two
paragraphs should be replaced with.

    HEAD records the state from which your current changes started.
    This can be a branch (the "current branch"), or it be a commit,
    (in which case HEAD is "detached").

    In the detached HEAD state, you can safely build, run, and
    experiment with any historical version of your codebase, without
    having to worry about clobbering your branches, and you do not
    have to clutter your repository with temporary branches.

Having said all that, the changes between v3 and v4 look OK to me,
so let me update the previous copy I have with this version.