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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 1, 2010, 17:38 UTC
Message-ID: <7vpr4o3lg9.fsf@alter.siamese.dyndns.org>
In-Reply-To: <31a97741002010352x1ad27f26ia4d51857bb2d2d4f@mail.gmail.com>

Steve Diver <squelch2@googlemail.com> writes:

> Would it be a safe assumption to describe a 'detached HEAD' state as
> being synonymous with a (local) personal scratchpad or temporary
> workspace based on and from the original committed object?

A commonly used term since we started discussing the detached HEAD late 2006 (v1.5.0 timeframe) is a "temporary branch" or a "throw-away" branch. See c847f53 (Detached HEAD (experimental), 2007-01-01), for example.

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?