Re: master^ is not a local branch -- huh?!?

On 1 February 2010 18:12, Nicolas Pitre [off-list ref] wrote:

On Mon, 1 Feb 2010, Junio C Hamano wrote:

quoted

I do not think we need yet another term "scratchpad" for this, but what is
important is that both introductory and full documentation explain the
detached HEAD well.

Currently we say:

    Detached HEAD
    -------------

    It is sometimes useful to be able to 'checkout' a commit that is
    not at the tip of one of your branches.  The most obvious
    example is to check out the commit at a tagged official release
    point, like this:

    ------------
    $ git checkout v2.6.18
    ------------

    Earlier versions of git did not allow this and asked you to
    create a temporary branch using the `-b` option, but starting from
    version 1.5.0, the above command 'detaches' your HEAD from the
    current branch and directly points at the commit named by the tag
    (`v2.6.18` in the example above).

If read carefully (some may argue that it does not need a very careful
reading to get it, though), this hints that "detached HEAD" state is a
substitute for using a temporary branch, but it may not be strong enough.

I thought that a documentation update in this area was already planned?

A "temporary branch" is probably the simplest description, and would
make it easier to grasp the concept in plain language for those that
are new to Git without glazing over.

Is how it worked pre version 1.5.0 now moot in terms of reference?
Probably the first encounter a user might have is when they arrive at
a detached HEAD situation and receive the message that prompted Ron
Garret to start this thread. The concept of an automatic temporary
branch might be easier to understand from the outset without needing
reference to the "old ways" ;)

As an aside, I believe a common misconception is for a user to think
they are checking out a single file revision which could be the most
likely mechanism to lead them into an inadvertent detached HEAD state.
Any improvement in both the first line message and the full
documentation would be most helpful.

Jay Soffian (added to CC) agreed to augment the documentation with the
comprehensive explanation he posted to the list lately.

That is good news indeed.

Steve