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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 29, 2010, 21:35 UTC
Message-ID: <7vzl3wh9wx.fsf@alter.siamese.dyndns.org>
In-Reply-To: <fabb9a1e1001291256j71e2c95cic21cb5a6a0cc1fe8@mail.gmail.com>

Sverre Rabbelier <srabbelier@gmail.com> writes:

Show 10 quoted lines

> On Fri, Jan 29, 2010 at 21:48, Junio C Hamano <gitster@pobox.com> wrote:
>> I think "not a branch" is a good suggestion, whether the target of
>> checkout is "master^" or "origin/topic".
>
> Mhhh, for added clarity, do we want to change it to "branch name"? Since ...
>
> $ git grep "branch name" Documentation/ | wc -l
> 58
>
> ... suggests that we use that in other places as well?

I think the confusion is twofold:

    $ git checkout master^
    Note: moving to 'master^' which isn't a local branch
    If you want to create a new branch from this checkout, you may do so
    ...

The notice tells us:

 - We are moving to 'master^', but it doesn't say what that really means;

 - That 'master^' isn't a local branch, but it doesn't say why it matters
   if it is a local branch (name) or not.

But what it really should tell new people are:

 - The user is no longer on any branch;

 - What the implications of not being on any branch are;

Your "branch _name_" suggestion deals with another issue that is of lessor importance compared to the above two:

 - The _reason_ we are detaching HEAD is because 'master^' did not spell a
   name of a local branch.

 - and perhaps how to be on a branch instead of detaching the head like so.

Compare the current output from "git checkout $commit" with output from "git checkout topic" when you don't have a local branch "topic" but have a unique remote tracking branch with the same name from a remote, namely "origin" (that's the UI improvement from Dscho I mentioned in the previous message):

    $ git checkout topic
    Branch topic set up to track remote branch topic from origin.
    Switched to a new branch 'topic'

which very clearly explains what is going on.

The current advisory message tells you what to do to create a new branch, but doesn't explain why you might want to do so (or what is the downside of not doing so) in the first place. That adds to frustration for new people.

So how about this strawman?

    $ git checkout origin/topic
    Note: checking out commit 'origin/topic'.
    You are no longer on any branch. You can look around, make changes and
    record them in new commits, but any new commit you make from now on will
    be lost when you check out another branch. If you want to create a new
    branch from this state to keep them, 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 f423ef5... tests: allow user to specify trash direc...

and hide the lines from "Note: checking out..." to the blank line before "HEAD is now at" inside advice.detachedHEAD, so that people who know what detached head is and want to take advantage of it to experiment without having to worry about cleaning up will have to see only:

    $ git checkout origin/topic
    HEAD is now at f423ef5... tests: allow user to specify trash direc...

diff --git a/advice.c b/advice.c
index 936d98b..0be4b5f 100644
--- a/advice.c
+++ b/advice.c
@@ -5,6 +5,7 @@ int advice_status_hints = 1;
 int advice_commit_before_merge = 1;
 int advice_resolve_conflict = 1;
 int advice_implicit_identity = 1;
+int advice_detached_head = 1;
 
 static struct {
 	const char *name;
@@ -15,6 +16,7 @@ static struct {
 	{ "commitbeforemerge", &advice_commit_before_merge },
 	{ "resolveconflict", &advice_resolve_conflict },
 	{ "implicitidentity", &advice_implicit_identity },
+	{ "detachedhead", &advice_detached_head },
 };
 
 int git_default_advice_config(const char *var, const char *value)
diff --git a/advice.h b/advice.h
index 9b7a3ad..3244ebb 100644
--- a/advice.h
+++ b/advice.h
@@ -8,6 +8,7 @@ extern int advice_status_hints;
 extern int advice_commit_before_merge;
 extern int advice_resolve_conflict;
 extern int advice_implicit_identity;
+extern int advice_detached_head;
 
 int git_default_advice_config(const char *var, const char *value);
 
diff --git a/builtin-checkout.c b/builtin-checkout.c
index 5277817..0719e54 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: checking out commit '%s'.\n"
+"You are no longer on any branch. You can look around, make changes and\n"
+"record them in new commits, but any new commit you make from now on will\n"
+"be lost when you check out another branch. If you want to create a new\n"
+"branch from this state to keep them, you may do so (now or later) by\n"
+"using -b with the checkout command again. Example:\n\n"
+"  git checkout -b new_branch_name\n\n",
+					new->name);
 			describe_detached_head("HEAD is now at", new->commit);
 		}
 	}