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

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

Nicolas Pitre <nico@fluxnic.net> writes:

> To the contrary, I think it is about time we use proper Git jargon.  
> Otherwise how can we expect people to relate to the documentation where 
> that jargon is indeed used?  Even on this very mailing list we refer to 
> that state as a "detached HEAD".  And Google gives precisely the right 
> info with "detached HEAD" while any other verbiage might not.
>
> And just saying that "you're not on any branch anymore" is still leaving 
> the user wondering why.  At least with the "isn't a local branch head" 
> the user has 2 clues: it has to be a _local_ branch and a branch _head_ 
> not to create a detached HEAD.  So I still prefer the above rewording.

I can buy that argument, except for three minor points:

 - I think we also should give information necessary to judge if the user
   wants to stay in the detached HEAD state.  IOW, "Why am I getting an
   insn to create a new branch?  What is wrong with this detached HEAD
   state?  Why would I want a local branch?" are still not explained with
   the updated message.

 - Do we "create" a detached HEAD, or are we just "detaching HEAD"?

 - Running "checkout -b" now will create a new branch from that checkout,
   but doing so _later_ won't necessarily do so from that _checkout_.

So how about doing this (changes to advice.[ch] are omitted)?

diff --git a/builtin-checkout.c b/builtin-checkout.c
index 5277817..41fc00a 100644
--- a/builtin-checkout.c
+++ b/builtin-checkout.c
@@ -522,8 +522,16 @@ static void update_refs_for_switch(struct checkout_opts *opts,
 		update_ref(msg.buf, "HEAD", new->commit->object.sha1, NULL,
 			   REF_NODEREF, DIE_ON_ERR);
 		if (!opts->quiet) {
-			if (old->path)
-				fprintf(stderr, "Note: moving to '%s' which isn't a local branch\nIf you want to create a new branch from this checkout, you may do so\n(now or later) by using -b with the checkout command again. Example:\n  git checkout -b <new_branch_name>\n", new->name);
+			if (old->path && advice_detached_head)
+				fprintf(stderr,
+"Note: '%s' isn't a local branch head.\n\n"
+"HEAD is detached at that commit. You can look around, even make changes\n"
+"and record them in new commits, but any new commit you make from now on\n"
+"will be lost when you check out another branch.\n"
+"If you want to create a new branch from this state, you may do so\n"
+"(now or later) by using -b with the checkout command again. Example:\n"
+"  git checkout -b <new_branch_name>\n\n",
+					new->name);
 			describe_detached_head("HEAD is now at", new->commit);
 		}
 	}