On 1 February 2010 18:12, Nicolas Pitre <nico@xxxxxxxxxxx> wrote: > On Mon, 1 Feb 2010, Junio C Hamano wrote: > >> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html