From: Jeff King <peff@peff.net>
Date: Sun, 12 Apr 2009 07:20:57 GMT
Subject: Re: [PATCH] builtin-branch - allow deleting a fully specified branch-name
Message-ID: <20090412072056.GA25837@coredump.intra.peff.net>
In-Reply-To: <200904111301.31250.mlevedahl@gmail.com>

On Sat, Apr 11, 2009 at 01:01:30PM -0400, Mark Levedahl wrote:

>    $ git checkout -b refs/heads/master refs/heads/master
>              creates a new branch, refname = refs/heads/refs/heads/master
> 
> The last command is the one that I find most curious. The exact same string 
> has two entirely different meanings to the same command. I can explain why 
> this happens, but I cannot explain why this is a good thing. 

A command like "grep foo foo" has the same property (one string with
different meanings based on argument position). The problem is that you
are thinking of it as:

  git checkout -b <branch> <branch>

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.

> A model I could explain without mental gymnastics would be "branch names are 
> simply refnames without the leading refs/heads or refs/remotes, and a refname 
> may be used wherever a branch name is requested. While branch names are 
> potentially ambiguous, refnames never are."  Of course, this would mean that 

So the current model is: "branch names are simply refnames without the
leading refs/heads or refs/remotes. A <commit> can be referenced by the
usual names (see git rev-parse, "specifying revisions" for details)".

The thing that I think is more confusing about that is not the
final example you pointed out, but the difference between

  git checkout master

and

  git checkout refs/heads/master

Which is explained by the fact that the usage for checkout is not

  git checkout <branch>

but actually

  git checkout <branch|commit>

If a branch, then we checkout the branch. If a commit, then we detach on
that commit.

I'm not sure if that explanation helps you at all, but that is how I
think of it (and it makes sense to me).

-Peff