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

From: Jeff King <peff@peff.net>
Date: Apr 13, 2009, 08:56 UTC
Message-ID: <20090413085622.GC9846@coredump.intra.peff.net>
In-Reply-To: <7v7i1qb7sw.fsf@gitster.siamese.dyndns.org>

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

Show 12 quoted lines

> > 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