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

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

[Mark Levedahl]

This change allows, for instance
	git branch -d refs/heads/foo
to succeed. Without this patch, the code just assumes that the
given branch name should be appended to "refs/heads" or
"refs/remotes", thus attempting (and failing) in the above case
to delete "refs/heads/refs/heads/foo"

Signed-off-by: Mark Levedahl <mlevedahl@gmail.com>
---
 builtin-branch.c |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/builtin-branch.c b/builtin-branch.c
index ca81d72..f433bc5 100644
--- a/builtin-branch.c
+++ b/builtin-branch.c
@@ -131,7 +131,11 @@ static int delete_branches(int argc, const char **argv, int force, int kinds)
 
 		free(name);
 
-		name = xstrdup(mkpath(fmt, bname.buf));
+		if (bname.len < 5 || memcmp("refs/", bname.buf, 5))
+			name = xstrdup(mkpath(fmt, bname.buf));
+		else
+			name = xstrdup(bname.buf);
+
 		if (!resolve_ref(name, sha1, 1, NULL)) {
 			error("%sbranch '%s' not found.",
 					remote, bname.buf);
-- 
1.6.2.2.27.g034b

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

[Junio C Hamano]

Mark Levedahl <mlevedahl@gmail.com> writes:

> This change allows, for instance
> 	git branch -d refs/heads/foo
> to succeed. Without this patch, the code just assumes that the
> given branch name should be appended to "refs/heads" or
> "refs/remotes", thus attempting (and failing) in the above case
> to delete "refs/heads/refs/heads/foo"

Your logic is broken.

Why doesn't the user simply say "git branch -d foo"?  The command takes
"the branch name", not "arbitrary ref name".

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

[Mark Levedahl]

On Thursday 09 April 2009 20:39:46 Junio C Hamano wrote:
> Mark Levedahl <mlevedahl@gmail.com> writes:
> > This change allows, for instance
> > 	git branch -d refs/heads/foo
> > to succeed. Without this patch, the code just assumes that the
> > given branch name should be appended to "refs/heads" or
> > "refs/remotes", thus attempting (and failing) in the above case
> > to delete "refs/heads/refs/heads/foo"
>
> Your logic is broken.
>
> Why doesn't the user simply say "git branch -d foo"?  The command takes
> "the branch name", not "arbitrary ref name".

1) git branch -d refs/<whatever> used to work,  I haven't bisected to find 
when this stopped working, but the change broke one of my scripts, so this is 
not new behavior, it is restoration of previous behavior.
2) If I create branch  refs/frotz/bar , how do I ever delete it?

Also, the following all work
3) git branch refs/heads/foo
4) git branch -m refs/heads/foo refs/heads/bar 
5) git  [checkout|pull|push|fetch|show] refs/heads/foo

So, why is "git branch -d" so special?

Mark

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

[Junio C Hamano]

Mark Levedahl <mlevedahl@gmail.com> writes:

> On Thursday 09 April 2009 20:39:46 Junio C Hamano wrote:
>> Mark Levedahl <mlevedahl@gmail.com> writes:
>> > This change allows, for instance
>> > 	git branch -d refs/heads/foo
>> > to succeed. Without this patch, the code just assumes that the
>> > given branch name should be appended to "refs/heads" or
>> > "refs/remotes", thus attempting (and failing) in the above case
>> > to delete "refs/heads/refs/heads/foo"
>>
>> Your logic is broken.
>>
>> Why doesn't the user simply say "git branch -d foo"?  The command takes
>> "the branch name", not "arbitrary ref name".
>
> 1) git branch -d refs/<whatever> used to work,  I haven't bisected to find 
> when this stopped working, but the change broke one of my scripts, so this is 
> not new behavior, it is restoration of previous behavior.

I need to look at the history, if that is the case then perhaps Ok.

> 2) If I create branch  refs/frotz/bar , how do I ever delete it?

By this you must mean .git/refs/heads/refs/frotz/bar, right?  Then
shouldn't "git branch -d refs/frotz/bar" just work as is?  If you are
talking about .git/refs/frotz/bar, "git branch" should not touch it, it is
not even a branch.

> Also, the following all work

> 3) git branch refs/heads/foo
> 4) git branch -m refs/heads/foo refs/heads/bar 

If you mean it creates .git/refs/heads/refs/heads/foo, then sure it
should.  If it creates .git/refs/heads/foo, I think it is broken.

> 5) git  [checkout|pull|push|fetch|show] refs/heads/foo

Among these, checkout is the only special case that can take "branch name"
to switch branches.  Everything else takes extended SHA-1 expression.
Checkout can interpret the first argument as "branch to switch to", but it
does not necessarily so---think "detached HEAD", and also think "checking
out paths out of tree-ish".

> So, why is "git branch -d" so special?

"git branch -d", "git branch -m" and friends all take branch name, and as
such it can use "@{-1}" to _name_ 'the previous branch".  In that context,
you are _not_ naming the commit at the tip of the branch.  You are naming
the branch itself.

All other commands happen to take a branch name because that is just one
case of extended SHA-1 expression to name an object.  In that context, a
refname (which a branch name is a special case of) refers to the commit
pointed by it.  E.g.

        "git checkout HEAD~20 -- Makefile"
        "git show refs/heads/foo"
        "git show heads/foo"
        "git show foo"

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

[Mark Levedahl]

On Thursday 09 April 2009 23:18:01 you wrote:
>
> All other commands happen to take a branch name because that is just one
> case of extended SHA-1 expression to name an object.  In that context, a
> refname (which a branch name is a special case of) refers to the commit
> pointed by it.  E.g.
>
>         "git checkout HEAD~20 -- Makefile"
>         "git show refs/heads/foo"
>         "git show heads/foo"
>         "git show foo"

I think my underlying problem here is the porcelain's ability to use either a 
branch name or a ref name, in different contexts, leading to a sometimes 
inconsistent interface. Consider the following
   $ git checkout master
             checks out branch master
   $ git checkout refs/heads/master
             checks out commit pointed to by refs/heads/master on a detached 
HEAD

   $ 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 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 
the refs/heads/refs/... namespace is illegal. I don't know of any other 
downside (except of course to someone using that namespace), and frankly I 
don't think the existence of the refs/heads/refs namespace is a good thing, 
given the potential for confusion.

Just a thought.

Mark

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

[Jeff King]

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

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

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.

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

[Jeff King]

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

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

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

I'd agree it would make it much nicer.

Thanks for a bit of sanity.  I sometimes misplace it when I got grumpy.

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

[Jeff King]

On Mon, Apr 13, 2009 at 04:56:22AM -0400, Jeff King wrote:

> > 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 meant to attach a patch here so you could judge for yourself, but I
forgot. I am preparing a patch series which I think is better, but for
reference, here is what I came up with before:

---
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 223ea9c..344c57a 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -131,15 +131,20 @@ the conflicted merge in the specified paths.
 	the index will be used.
 
 <branch>::
-	Branch to checkout (when no paths are given); may be any object
-	ID that resolves to a commit.  Defaults to HEAD.
+	If "-b" is not given, specifies the branch to checkout. If it
+	names a non-branch (i.e., a name that, when prepended with
+	"refs/heads/", does not exist) but does point to a
+	valid commit object, then the HEAD becomes 'detached', and you
+	are no longer on any branch.  As a special case, the `"@\{-N\}"`
+	syntax for the N-th last branch checks out the branch (instead
+	of detaching).  You may also specify `-` which is synonymous
+	with `"@\{-1\}"`.
 +
-When this parameter names a non-branch (but still a valid commit object),
-your HEAD becomes 'detached'.
+If "-b" is given, specifies the start point of the newly created
+branch. Specifying a non-branch is irrelevant here, since git will
+checkout the newly created branch, not the start point.
 +
-As a special case, the `"@\{-N\}"` syntax for the N-th last branch
-checks out the branch (instead of detaching).  You may also specify
-`-` which is synonymous with `"@\{-1\}"`.
+In either case, if the parameter is omitted, it defaults to HEAD.
 
 
 Detached HEAD

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

[Jeff King]

On Mon, Apr 13, 2009 at 02:54:27AM -0700, Junio C Hamano wrote:

> > 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.
> 
> I'd agree it would make it much nicer.

A 5-patch series follows which does this and a few other fixups. I think
the result is better.

  1/5 doc: clarify --no-track option
  2/5 doc: refer to tracking configuration as "upstream"
  3/5 doc/checkout: refer to git-branch(1) as appropriate
  4/5 doc/checkout: split checkout and branch creation in synopsis
  5/5 docs/checkout: clarify what "non-branch" means

-Peff

[PATCH 1/5] doc: clarify --no-track option

[Jeff King]

It is not really about ignoring the config option; it is
about turning off tracking, _even if_ the config option is
set.

Signed-off-by: Jeff King <peff@peff.net>
---
This I just noticed while working in the area, and it bothered me.

 Documentation/git-branch.txt   |    3 ++-
 Documentation/git-checkout.txt |    3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ba3dea6..19f1b0d 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -124,7 +124,8 @@ OPTIONS
 	start-point is either a local or remote branch.
 
 --no-track::
-	Ignore the branch.autosetupmerge configuration variable.
+	Do not set up tracking configuration, even if the
+	branch.autosetupmerge configuration variable is true.
 
 --contains <commit>::
 	Only list branches which contain the specified commit.
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 223ea9c..4992fc6 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -90,7 +90,8 @@ guessing results in an empty name, the guessing is aborted.  You can
 explicitly give a name with '-b' in such a case.
 
 --no-track::
-	Ignore the branch.autosetupmerge configuration variable.
+	Do not set up tracking configuration, even if the
+	branch.autosetupmerge configuration variable is true.
 
 -l::
 	Create the new branch's reflog.  This activates recording of
-- 
1.6.3.rc0.148.g141203.dirty

[PATCH 2/5] doc: refer to tracking configuration as "upstream"

[Jeff King]

The term "tracking" often creates confusion between remote
tracking branches and local branches which track a remote
branch. The term "upstream" captures more clearly the idea
of "branch A is based on branch B in some way", so it makes
sense to mention it.

At the same time, upstream branches are used for more
than just git-pull these days; let's mention that here.

Signed-off-by: Jeff King <peff@peff.net>
---
I think this matches nicely with Santi's recent addition of upstream to
the glossary.

 Documentation/git-branch.txt   |   24 +++++++++++++-----------
 Documentation/git-checkout.txt |    2 +-
 2 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 19f1b0d..cbd4275 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -112,19 +112,21 @@ OPTIONS
 	Display the full sha1s in the output listing rather than abbreviating them.
 
 --track::
-	When creating a new branch, set up the configuration so that 'git-pull'
-	will automatically retrieve data from the start point, which must be
-	a branch. Use this if you always pull from the same upstream branch
-	into the new branch, and if you do not want to use "git pull
-	<repository> <refspec>" explicitly. This behavior is the default
-	when the start point is a remote branch. Set the
-	branch.autosetupmerge configuration variable to `false` if you want
-	'git-checkout' and 'git-branch' to always behave as if '--no-track' were
-	given. Set it to `always` if you want this behavior when the
-	start-point is either a local or remote branch.
+	When creating a new branch, set up configuration to mark the
+	start-point branch as "upstream" from the new branch. This
+	configuration will tell git to show the relationship between the
+	two branches in `git status` and `git branch -v`. Furthermore,
+	it directs `git pull` without arguments to pull from the
+	upstream when the new branch is checked out.
++
+This behavior is the default when the start point is a remote branch.
+Set the branch.autosetupmerge configuration variable to `false` if you
+want `git checkout` and `git branch` to always behave as if '--no-track'
+were given. Set it to `always` if you want this behavior when the
+start-point is either a local or remote branch.
 
 --no-track::
-	Do not set up tracking configuration, even if the
+	Do not set up "upstream" configuration, even if the
 	branch.autosetupmerge configuration variable is true.
 
 --contains <commit>::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4992fc6..16d3c87 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -90,7 +90,7 @@ guessing results in an empty name, the guessing is aborted.  You can
 explicitly give a name with '-b' in such a case.
 
 --no-track::
-	Do not set up tracking configuration, even if the
+	Do not set up "upstream" configuration, even if the
 	branch.autosetupmerge configuration variable is true.
 
 -l::
-- 
1.6.3.rc0.148.g141203.dirty

[PATCH 3/5] doc/checkout: refer to git-branch(1) as appropriate

[Jeff King]

Most of description for the branch creation options is
simply cut and paste from git-branch. There are two reasons
to fix this:

  1. It can grow stale with respect to what's in "git
     branch" (which it is now is).

  2. It is not just an implementation detail, but rather the
     desired mental model for the command that we are using
     "git branch" here. Being explicit about that can help
     the user understand what is going on.

It also makes sense to strip the branch creation options
from the synopsis, as they are making it a long,
hard-to-read line. They are still easily discovered by
reading the options list, and --track is explicitly
referenced when branch creation is described.

Signed-off-by: Jeff King <peff@peff.net>
---
There are two things here that people might disagree with:

 1. Referring the user instead of using asciidoc magic to just include
    the repeated text. While it is nice to save the user the effort
    of referencing the other documentation, I think sometimes we go too
    far with this in git. Sometimes it is beneficial for the user not
    just to get the information, but to have it pointed out that the
    link exists. Then they can better understand exactly what it is git
    is doing (it is not "oh, this is a totally unrelated way to create
    branches" but "this is a convenience wrapper that calls git branch"
    -- I think the latter is the model we want to use).

 2. Shortening the synopsis field. The long lines look awful in the
    manpage on an 80-column terminal. I don't read git documentation
    very often, so I have not really noticed, but some of our synopses
    are quite complex and IMHO unreadable. We are much better off just
    saying "there are some options, then these 1 or 2 arguments" which
    give an overview of how you would invoke the command. You can look
    at the option list if you want to actually see the options.

    In this patch I just shortened the ones related to branch creation.
    But I was tempted to take this a step further and get rid of the
    "-f", "-q", and "-m" options in the synopsis, as well, which I think
    would look much better.

 Documentation/git-checkout.txt |   28 +++++++++-------------------
 1 files changed, 9 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 16d3c87..22ad10d 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree
 SYNOPSIS
 --------
 [verse]
-'git checkout' [-q] [-f] [-t | --track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
+'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<branch>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 
 DESCRIPTION
@@ -18,8 +18,9 @@ When <paths> are not given, this command switches branches by
 updating the index and working tree to reflect the specified
 branch, <branch>, and updating HEAD to be <branch> or, if
 specified, <new_branch>.  Using -b will cause <new_branch> to
-be created; in this case you can use the --track or --no-track
-options, which will be passed to `git branch`.
+be created as if linkgit:git-branch[1] were called; in this case you can
+use the --track or --no-track options, which will be passed to `git
+branch`.
 
 As a convenience, --track will default to creating a branch whose
 name is constructed from the specified branch name by stripping
@@ -62,22 +63,12 @@ entries; instead, unmerged entries are ignored.
 
 -b::
 	Create a new branch named <new_branch> and start it at
-	<branch>.  The new branch name must pass all checks defined
-	by linkgit:git-check-ref-format[1].  Some of these checks
-	may restrict the characters allowed in a branch name.
+	<branch>; see linkgit:git-branch[1] for details.
 
 -t::
 --track::
-	When creating a new branch, set up configuration so that 'git-pull'
-	will automatically retrieve data from the start point, which must be
-	a branch. Use this if you always pull from the same upstream branch
-	into the new branch, and if you don't want to use "git pull
-	<repository> <refspec>" explicitly. This behavior is the default
-	when the start point is a remote branch. Set the
-	branch.autosetupmerge configuration variable to `false` if you want
-	'git checkout' and 'git branch' to always behave as if '--no-track' were
-	given. Set it to `always` if you want this behavior when the
-	start point is either a local or remote branch.
+	When creating a new branch, set up "upstream" configuration. See
+	"--track" in linkgit:git-branch[1] for details.
 +
 If no '-b' option is given, the name of the new branch will be
 derived from the remote branch.  If "remotes/" or "refs/remotes/"
@@ -94,9 +85,8 @@ explicitly give a name with '-b' in such a case.
 	branch.autosetupmerge configuration variable is true.
 
 -l::
-	Create the new branch's reflog.  This activates recording of
-	all changes made to the branch ref, enabling use of date
-	based sha1 expressions such as "<branchname>@\{yesterday}".
+	Create the new branch's reflog; see linkgit:git-branch[1] for
+	details.
 
 -m::
 --merge::
-- 
1.6.3.rc0.148.g141203.dirty

[PATCH 4/5] doc/checkout: split checkout and branch creation in synopsis

[Jeff King]

These can really be thought of as two different modes, since
the "<branch>" parameter is treated differently in the two
(in one it is the branch to be checked out, but in the other
it is really a start-point for branch creation).

Signed-off-by: Jeff King <peff@peff.net>
---
This was the actual goal of the series. :)

 Documentation/git-checkout.txt |   40 ++++++++++++++++++++++------------------
 1 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 22ad10d..4a1fb53 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,23 +8,22 @@ git-checkout - Checkout a branch or paths to the working tree
 SYNOPSIS
 --------
 [verse]
-'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<branch>]
+'git checkout' [-q] [-f] [-m] [<branch>]
+'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 
 DESCRIPTION
 -----------
 
 When <paths> are not given, this command switches branches by
-updating the index and working tree to reflect the specified
-branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
-be created as if linkgit:git-branch[1] were called; in this case you can
-use the --track or --no-track options, which will be passed to `git
-branch`.
+updating the index, working tree, and HEAD to reflect the specified
+branch.
 
-As a convenience, --track will default to creating a branch whose
-name is constructed from the specified branch name by stripping
-the first namespace level.
+If `-b` is given, a new branch is created and checked out, as if
+linkgit:git-branch[1] were called; in this case you can
+use the --track or --no-track options, which will be passed to `git
+branch`.  As a convenience, --track without `-b` implies branch
+creation; see the description of --track below.
 
 When <paths> are given, this command does *not* switch
 branches.  It updates the named paths in the working tree from
@@ -63,7 +62,7 @@ entries; instead, unmerged entries are ignored.
 
 -b::
 	Create a new branch named <new_branch> and start it at
-	<branch>; see linkgit:git-branch[1] for details.
+	<start_point>; see linkgit:git-branch[1] for details.
 
 -t::
 --track::
@@ -114,13 +113,6 @@ the conflicted merge in the specified paths.
 	"merge" (default) and "diff3" (in addition to what is shown by
 	"merge" style, shows the original contents).
 
-<new_branch>::
-	Name for the new branch.
-
-<tree-ish>::
-	Tree to checkout from (when paths are given). If not specified,
-	the index will be used.
-
 <branch>::
 	Branch to checkout (when no paths are given); may be any object
 	ID that resolves to a commit.  Defaults to HEAD.
@@ -132,6 +124,18 @@ As a special case, the `"@\{-N\}"` syntax for the N-th last branch
 checks out the branch (instead of detaching).  You may also specify
 `-` which is synonymous with `"@\{-1\}"`.
 
+<new_branch>::
+	Name for the new branch.
+
+<start_point>::
+	The name of a commit at which to start the new branch; see
+	linkgit:git-branch[1] for details. Defaults to HEAD.
+
+<tree-ish>::
+	Tree to checkout from (when paths are given). If not specified,
+	the index will be used.
+
+
 
 Detached HEAD
 -------------
-- 
1.6.3.rc0.148.g141203.dirty

[PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Jeff King]

In the code we literally stick "refs/heads/" on the front
and see if it resolves, so that is probably the best
explanation.

Signed-off-by: Jeff King <peff@peff.net>
---
I hope this helps a little bit with Mark's confusion. But while writing
it, I really think it would be a simpler rule to say "if it's in
refs/heads/, then it's a branch" (which is similar to what Mark
suggested earlier).

So "git checkout refs/heads/master" would be identical to "git checkout
master". That would require a code change, though.

 Documentation/git-checkout.txt |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4a1fb53..ad4b31e 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -114,11 +114,11 @@ the conflicted merge in the specified paths.
 	"merge" style, shows the original contents).
 
 <branch>::
-	Branch to checkout (when no paths are given); may be any object
-	ID that resolves to a commit.  Defaults to HEAD.
-+
-When this parameter names a non-branch (but still a valid commit object),
-your HEAD becomes 'detached'.
+	Branch to checkout; if it refers to a branch (i.e., a name that,
+	when prepended with "refs/heads/", is a valid ref), then that
+	branch is checked out. Otherwise, if it refers to a valid
+	commit, your HEAD becomes "detached" and you are no longer on
+	any branch (see below for details).
 +
 As a special case, the `"@\{-N\}"` syntax for the N-th last branch
 checks out the branch (instead of detaching).  You may also specify
-- 
1.6.3.rc0.148.g141203.dirty

Re: [PATCH 4/5] doc/checkout: split checkout and branch creation in synopsis

[Jeff King]

On Mon, Apr 13, 2009 at 03:13:06PM +0200, Sverre Rabbelier wrote:

> On Mon, Apr 13, 2009 at 13:19, Jeff King <peff@peff.net> wrote:
> > +'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
> 
> This way doesn't it say you can leave out the [-b <new branch>] part
> but still specify a start point? I thought the general syntax for this
> would make it:
> 
> > +'git checkout' [-q] [-f] [-m] [-b <new_branch> [<start_point>]]

Oops, actually it is supposed to be:

 'git checkout' ... -b <new_branch> [<start_point>]

The cause where "-b <new_branch>" isn't used is covered in the line
above.

-Peff

Re: [PATCH 4/5] doc/checkout: split checkout and branch creation in synopsis

[Sverre Rabbelier]

Heya,

On Mon, Apr 13, 2009 at 15:19, Jeff King <peff@peff.net> wrote:
>  'git checkout' ... -b <new_branch> [<start_point>]
>
> The cause where "-b <new_branch>" isn't used is covered in the line
> above.

Ah, it is indeed, thatm akes it even more readable! :)

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I hope this helps a little bit with Mark's confusion. But while writing
> it, I really think it would be a simpler rule to say "if it's in
> refs/heads/, then it's a branch" (which is similar to what Mark
> suggested earlier).
>
> So "git checkout refs/heads/master" would be identical to "git checkout
> master". That would require a code change, though.

Sorry, but I do not get the logic behind such a change.

Because you won't be breaking "git checkout frotz" that checks out the
branch whose name is frotz (i.e. refs/heads/frotz) even when a tag frotz
exists (i.e. refs/tags/frotz), the updated code cannot be "try to resolve
the token given from the command line as-is, and if it is in refs/heads/
it is a branch switch, otherwise it is a detach at the commit".  The
updated code has to be "try to resolve the token appended to refs/heads
and if it resolves, that is a branch switch.  Otherwise if the token
already begins with refs/heads/ then it also is a switch to the branch
whose name is the token minus the leading refs/heads/, otherwise try to
resolve it as-is and detach at that commit".

The result changes behaviour for two classes of people.

 (1) People who have a branch whose name is refs/heads/frotz.  Before they
     could switch to the branch by mechanically giving its name.  Now they
     have to remember that such a branch with an unusual name needs to be
     fully spelled "git checkout refs/heads/refs/heads/frotz".

 (2) People who have scripts that gets a refname (or a list of refnames),
     and drive "git checkout" to either switch to the branch if that ref
     is a branch or detach at the commit if it isn't.  Their script had to
     check if the ref begins with refs/heads/ and if so strip that before
     giving it to "git checkout", but with your change they do not have
     to.

The former technically is a usability regression which I presume we do not
care.  The user with such a branch name is sick enough and deserve to be
punished ;-)

The latter might be improvement, but does it really matter?

Such a script is already checking with refs/heads/ (and it is easy to
codify in a script anyway), and with or without the change you suggest, it
will check out the master branch when the ref is refs/heads/master and the
script strips the leading refs/heads/.  With the change, it also needs to
delete the logic of stripping refs/heads/ to deal with (1) sanely.

In addition, most likely such a script to check out a series of refs in an
automated fashion is about autobuilding random set of commits, and it
would probably be better off working on the HEAD detached at given commit,
whether the incoming ref happens to be a branch ref or not.

So I am still scratching my head, wondering what improvement from the end
user's point of view you will be getting from such a change...

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Mark Levedahl]

On Monday 13 April 2009 12:31:31 Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> > I hope this helps a little bit with Mark's confusion. But while writing
> > it, I really think it would be a simpler rule to say "if it's in
> > refs/heads/, then it's a branch" (which is similar to what Mark
> > suggested earlier).
> >
> > So "git checkout refs/heads/master" would be identical to "git checkout
> > master". That would require a code change, though.
>
> Sorry, but I do not get the logic behind such a change.
>

I think the question being posed is: Would unifying branch names across all 
git commands (i.e., always accepting refs/heads/master as naming branch 
master, and accepting master when that is unambiguous) sufficiently benefit 
new users trying to learn git that it would be worth the change? The fact that 
refs/heads/master will be interpreted as branch or non-branch, and possibly as 
refs/heads/refs/heads/master, being a different branch, across different git 
commands is certainly not "intuitively obvious" to new users.

In this vein, I suggest that
	$ git checkout --detach master
as a way to get a detached HEAD on branch master is more understandable than
	$ git checkout refs/heads/master

Mark

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Junio C Hamano]

Mark Levedahl <mlevedahl@gmail.com> writes:

> I think the question being posed is: Would unifying branch names across all 
> git commands (i.e., always accepting refs/heads/master as naming branch 
> master, and accepting master when that is unambiguous) sufficiently benefit 
> new users...

My knee-jerk reaction is that what you are saying is backwards.

When do new people even need to know about refs/heads vs refs/tags with
modern Porcelain command set?

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Jakub Narebski]

Mark Levedahl wrote:


> In this vein, I suggest that
>       $ git checkout --detach master
> as a way to get a detached HEAD on branch master is more understandable than
>       $ git checkout refs/heads/master

To detach, use
        $ git checkout master^0

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Jeff King]

On Mon, Apr 13, 2009 at 09:31:31AM -0700, Junio C Hamano wrote:

> > I hope this helps a little bit with Mark's confusion. But while writing
> > it, I really think it would be a simpler rule to say "if it's in
> > refs/heads/, then it's a branch" (which is similar to what Mark
> > suggested earlier).
> >
> > So "git checkout refs/heads/master" would be identical to "git checkout
> > master". That would require a code change, though.
> 
> Sorry, but I do not get the logic behind such a change.

It is entirely about simplifying the mental model of "what is a branch"
for the user, and making it easier to explain in the documentation.

I think otherwise your analysis was right: it doesn't really buy much in
practical usage, and it slightly hurts people with crazy branch names
like "refs/heads/refs/heads/foo" (but I consider that unlikely enough
not to worry about).

-Peff

Re: [PATCH 5/5] docs/checkout: clarify what "non-branch" means

[Jeff King]

On Tue, Apr 14, 2009 at 01:36:58PM +0200, Jakub Narebski wrote:

> > In this vein, I suggest that
> >       $ git checkout --detach master
> > as a way to get a detached HEAD on branch master is more understandable than
> >       $ git checkout refs/heads/master
> 
> To detach, use
>         $ git checkout master^0

I have often though a "--detach" would be useful, just because the ref^0
syntax is so mysterious (and yes, _I_ know what it does, but explaining
why it works to a novice git user is just painful).

-Peff