Re: [PATCH/RFC] builtin-checkout: suggest creating local branch when appropriate to do so

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

Jeff King <peff@peff.net> writes:

> On Tue, Oct 13, 2009 at 05:31:46PM -0400, Daniel Barkalow wrote:
>
>> I personally think that the real issue is that our "detached HEAD" message 
>> is still too scary, and what we really want is to issue the scary message 
>> when using "git commit" to move a detached HEAD from what was checked out 
>> to a new commit. So:
>
> This has been discussed before (I happen to agree with you, but you
> probably want to address other comments in the thread):
>
>   http://thread.gmane.org/gmane.comp.version-control.git/38201/focus=38213

I just re-read the discussion again (thanks for a useful pointers).  I
mostly agree with everything said in the thread and obviously agree with
its conclusion, but one thing I noticed that everybody (who _was_ a git
expert) in the thread was assuming bothered me somewhat.

In this sequence:

    1$ git checkout $commit_name_that_is_not_a_local_branch
    2$ git commit; hack; hack; hack;...
    3$ git checkout $branch_name

Step #1 is where the HEAD is detached.  It is correct to argue that
detached HEAD is a different state and we should inform unsuspecting
users, which we do.

Step #2 is where a commit that is not connected to any ref is made.

Step #3 is where the state built in the detached HEAD "branch" vanishes
into lost-found.

The experts argued that #3 is where it is dangerous, and while it is
technically correct, an unsuspecting non-expert would not even _know_ that
nothing dangerous is happening while in step #2.

If the commit name used in step #1 were "v1.0.0", and if the user while in
step #2 ran "gitk v1.0.0" (or "git log v1.0.0"), he will be confused by
not seeing the recent commits.  The distinction between "detached HEAD"
and being on a branch needs to be understood to appreciate this (and taken
advantage of, when running e.g. "git show-branch v1.0.0 HEAD").

Way before step #3, such a user, even though technically not in any danger
yet, would be confused and panic: "I wanted to fix something in the 1.0.0
release, but where did my fix go?"

The current message in step #1 reads like this:

    $ git checkout origin/next
    Note: moving to 'origin/next' 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 9ecb2a7... Merge branch 'maint'

And perhaps for people who do not understand the second point in the
four-point list [*1*] I showed earlier in the thread, "If you want to
create a new branch" may not be descriptive enough, as a sight-seer and an
occasional typofixer, the user does not know what branch is good for to
begin with, and would not be able to tell if s/he even "wants to create"
one.  Perhaps it would help more if we reworded three lines after "Note:"
with something like:

    To keep the history of commits you will build from now on in a branch,
    you may want to do "git checkout -b <new-branch-name>" now.

and customize the "in a branch" and <new-branch-name> part if the checkout
was given a remote tracking branch and the corresponding local branch does
not yet exist, e.g. in the above example:

    To keep the history of commits you will build from now on in 'next'
    branch, you may want to do "git checkout -b next" now.


[Footnote]

*1* The world model in which a git user works is:

 * You clone and get copies of where the other end has its branches;

 * You do all your work on your local branches;

 * You may incorporate what the other end further did by merging from the
   tracking branch from it;

 * You update the other end by pushing what you did on your local branches.

I do not think you can nor should hide them from the user [*2*].

*2* We had to repeat "don't hide but teach" many times until it finally
sank in for another essential thing in the git world model.  I hope we do
not have to do the same repeating for the above four points.  Luckily we
do not have to repeat "don't hide but teach" about the index anymore these
days.