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

Jeff King <peff@peff.net> writes:

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.