Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name

On Sun, Apr 12, 2009 at 01:22:23AM -0700, Junio C Hamano wrote:

quoted

And I can see why you might think of it that way, because that is what
the synopsis in git-checkout(1) says. :) But it is really:

  git checkout -b <branch> <commit>

I'm not sure if changing that synopsis would really help, or if it is
a bit too subtle.

I think in many places we used to be stricter in terminology (e.g. when we
only need tree-ish we used to write tree-ish) but during the "usability
and approachiablility drive" people updated doc with "most of the time the
command takes commit, so we say commit".

Yeah, I think this is one of the fundamental usability debates of git.
On one hand, if you assume that the user learns about the object types,
the DAG, and refs, then all of this is very straightforward to explain.
The price you pay is a steep learning curve. On the other, you can get
95% of what you need done without ever being exposed to the technical
details, so I can see why people push for learning materials that gloss
over it.

I think "the apporachable part" aka "synopsis" should be kept the way it
is, but we should clarify in the description when the most general form is
different from the white lie we feed to newbies.

Hmm. I tried something in this direction, but I actually think it ended
up more confusing.

I think it would be better in the synopsis to split this into two use
cases:

  git checkout [<branch>]
  git checkout -b <new_branch> [<start_point>]

And then explain them as separate definitions.

-Peff