Reword "detached HEAD" notification

The old "advice" message explained how to create a branch after going into
a detached HEAD state but didn't make it clear why the user may want to do
so.  Also "moving to ... which isn't a local branch" was unclear if it is
complaining, if it is describing the new state, or if it is explaining why
the HEAD is detached (the true reason is the last one).

Give the established phrase 'detached HEAD' first to make it easy for
users to look up the concept in documentation, and briefly describe what
can be done in the state (i.e. play around without having to clean up)
before telling the user how to keep what was done during the temporary
state.

Allow the long description to be hidden by setting advice.detachedHead
configuration to false.

We might want to customize the advice depending on how the commit to check
out was spelled (e.g. instead of "new-branch-name", we way want to say
"topic" when "git checkout origin/topic" triggered this message) in later
updates, but this encapsulates that into a separate function and it should
be a good first step.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 17901e244a832efde1f6264957c8f9e8c2bd448a..fee44d8a4ab5f2f59baa320f9f72b004d5d5ad3c 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -138,6 +138,11 @@ advice.*::
                Advice on how to set your identity configuration when
                your information is guessed from the system username and
                domain name. Default: true.
+
+       detachedHead::
+               Advice shown when you used linkgit::git-checkout[1] to
+               move to the detach HEAD state, to instruct how to create
+               a local branch after the fact.  Default: true.
 --
 
 core.fileMode::

diff --git a/advice.c b/advice.c
index 936d98ba2ba2c597f69188c8e7f9f1abcc7169a8..0be4b5f008e1646946ba12fa5e51aa0830911ece 100644 (file)
--- 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 9b7a3ad1ca126cb882e87d400820043043061f78..3244ebb5c1caffebaaf8f28ce221533c38ec29b5 100644 (file)
--- 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 527781728e0706b906a94ddfb8ee2e8bb06fa05e..c5ab7835e1fe260b9ec61f216bf198011eabf6f7 100644 (file)
--- a/builtin-checkout.c
+++ b/builtin-checkout.c
@@ -488,6 +488,20 @@ static void report_tracking(struct branch_info *new)
        strbuf_release(&sb);
 }
 
+static void detach_advice(const char *old_path, const char *new_name)
+{
+       const char fmt[] =
+       "Note: checking out '%s'.\n\n"
+       "You are in 'detached HEAD' state. You can look around, make experimental\n"
+       "changes and commit them, and you can discard any commits you make in this\n"
+       "state without impacting any branches by performing another checkout.\n\n"
+       "If you want to create a new branch to retain commits you create, you may\n"
+       "do so (now or later) by using -b with the checkout command again. Example:\n\n"
+       "  git checkout -b new_branch_name\n\n";
+
+       fprintf(stderr, fmt, new_name);
+}
+
 static void update_refs_for_switch(struct checkout_opts *opts,
                                   struct branch_info *old,
                                   struct branch_info *new)
@@ -522,8 +536,8 @@ 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)
+                               detach_advice(old->path, new->name);
                        describe_detached_head("HEAD is now at", new->commit);
                }
        }

diff --git a/t/t7201-co.sh b/t/t7201-co.sh
index 6442f710be8bcaea11931044d52deb5b75d8f7e0..d20ed61b481539b25c054c49bd82aa6fb9b3a981 100755 (executable)
--- a/t/t7201-co.sh
+++ b/t/t7201-co.sh
@@ -166,19 +166,31 @@ test_expect_success 'checkout -m with merge conflict' '
        ! test -s current
 '
 
-test_expect_success 'checkout to detach HEAD' '
+test_expect_success 'checkout to detach HEAD (with advice declined)' '
 
+       git config advice.detachedHead false &&
        git checkout -f renamer && git clean -f &&
        git checkout renamer^ 2>messages &&
-       (cat >messages.expect <<EOF
-Note: moving to '\''renamer^'\'' 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>
-HEAD is now at 7329388... Initial A one, A two
-EOF
-) &&
-       test_cmp messages.expect messages &&
+       grep "HEAD is now at 7329388" messages &&
+       test 1 -eq $(wc -l <messages) &&
+       H=$(git rev-parse --verify HEAD) &&
+       M=$(git show-ref -s --verify refs/heads/master) &&
+       test "z$H" = "z$M" &&
+       if git symbolic-ref HEAD >/dev/null 2>&1
+       then
+               echo "OOPS, HEAD is still symbolic???"
+               false
+       else
+               : happy
+       fi
+'
+
+test_expect_success 'checkout to detach HEAD' '
+       git config advice.detachedHead true &&
+       git checkout -f renamer && git clean -f &&
+       git checkout renamer^ 2>messages &&
+       grep "HEAD is now at 7329388" messages &&
+       test 1 -lt $(wc -l <messages) &&
        H=$(git rev-parse --verify HEAD) &&
        M=$(git show-ref -s --verify refs/heads/master) &&
        test "z$H" = "z$M" &&