Re: [PATCH 02/13] Use current "detached HEAD" message

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Aug 25, 2013, 03:49 UTC
Message-ID: <20130825034916.GB2882@elie.Belkin>
In-Reply-To: <1667680014.1090850.1377329140347.JavaMail.ngmail@webmail08.arcor-online.net>

Thomas Ackermann wrote:

Show 22 quoted lines

> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -312,10 +312,17 @@ referenced by a tag:
>  
>  	------------------------------------------------
>  	$ git checkout v2.6.17
> -	Note: moving to "v2.6.17" which isn't a local branch
> -	If you want to create a new branch from this checkout, you may do so
> -	(now or later) by using -b with the checkout command again. Example:
> -	  git checkout -b <new_branch_name>
> +	Note: checking out 'v2.6.17'.
> +
> +	You are in 'detached HEAD' state. You can look around, make experimental
> +	changes and commit them, and you can discard any commits you make in this
> +	state without impacting any branches by performing another checkout.
> +
> +	If you want to create a new branch to retain commits you create, you may
> +	do so (now or later) by using -b with the checkout command again. Example:
> +
> +	  git checkout -b new_branch_name
> +
>  	HEAD is now at 427abfa... Linux v2.6.17

I wonder if this longer wall of text (added in 13be3e31, 2010-01-29) is too aggressive.

It is the only piece of advice that I explicitly disable in ~/.gitconfig, so I haven't looked at it again for a while. Since then, the usual stream of questions about how to recover from people who accidentally detached HEAD has still been showing up in #git, so I don't think the message succeeded in its purpose.

That might be partly because it is too long to digest at a glance.

When I see this message, what I actually take in is

                  $ git checkout v1.7.3
 Hmm, capital --->Note: checking out 'v1.7.3'.
 heading before
 lowercase        You are in 'detached HEAD' state. You ...
 sentence.
                                                            ... checkout.

                  If you want ...
                  do so (now or later) by using -b               .... Example:

                    git ...

                  HEAD is ...
 Phew, I can ---->$
 type commands
 again.

Whereas I think the message is just meant to convey the following:

      $ git checkout v2.6.17
      note: checking out a tag for inspection and discardable experiments on top

      To create a new branch to save your changes:

            git checkout -b my-branch-based-on-v2.6.17

      HEAD is now at 427abfa... Linux v2.6.17
      $

Show 8 quoted lines

>  ------------------------------------------------
>  
> @@ -326,7 +333,7 @@ and git branch shows that you are no longer on a branch:
>  $ cat .git/HEAD
>  427abfa28afedffadfca9dd8b067eb6d36bac53f
>  $ git branch
> -* (no branch)
> +* (detached from v2.6.17)

	grep "no branch" Documentation/user-manual.txt

finds two other instances of that message, which this branch doesn't touch. One is about a bisection, where (no branch) is pretty close to the actual message ('(no branch, bisect started on master)'). The other is about submodules. Here's a patch for potential squashing in that corrects it.

Thanks, Jonathan

diff --git i/Documentation/user-manual.txt w/Documentation/user-manual.txt
index 3e226190..b76219ee 100644
--- i/Documentation/user-manual.txt
+++ w/Documentation/user-manual.txt
@@ -3647,7 +3647,7 @@ working on a branch.
 
 -------------------------------------------------
 $ git branch
-* (no branch)
+* (detached from d266b98)
   master
 -------------------------------------------------