patchClarify the git-branch documentation of default start-point

For someone not deeply into git it is easy to assume that start-point of git-branch will deafult to origin/remotebranch when executing the following command sequence:

  git checkout origin/remotebranch
  git branch localbranch

This change clarifies the git-branch documentation regarding this.
---
 Documentation/git-branch.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

Martin Nordholts <enselic@gmail.com> writes:

The first new sentence says

	$ git checkout origin/next

does not mean you will be _on_ the remote branch, 'next' you got from me in this example. By definition you cannot be on anything but a local branch, so the sentence is correct.

But "it" in the second new sentence is unclear.

You probably wanted to answer "If I wanted to have _my own 'next' branch_ that tracks 'next' from the remote, what should I do?"

And the answer would be either

	$ git checkout -t -b next origin/next

or its shorthand invented by Dscho which is

	$ git checkout -t origin/next

Now, is "it must be (an) explicit(l)y specified" a correct instruction to lead the readers to these solutions?

On Wed, 2009-06-17 at 22:48 -0700, Junio C Hamano wrote:

What I am trying to clarify is that a remote branch will never be the default for the start-point argument to git-branch, so if someone wants a remote branch as start-point, then the branch must be explicitly specified.

For this, the first sentence might actually be enough. If a remote branch never is the current branch, and if start-point defaults to the current branch, then the start-point can never default to a remote branch.

Should we just stick to the first sentence then perhaps?

 / Martin

Martin Nordholts <enselic@gmail.com> writes:

Because I misread your updated documentation, somehow I thought you were talking about "checkout -b". Sorry for getting confused (and perhaps giving a confusing answer).

There are two concepts you seem to be confused about: <start-point> and branch tracking.

<start-point>, the term being explained in the part your patch touched, is only about what commit the newly created branch points at. In git, a branch is a label that attaches to an existing commit [*1*]. The form was originally:

	git branch <branchname> [<start-point>]

which is very straight-forward. The branch is created and points at the commit your HEAD points at. The description was later changed to "the current branch" in order to cater to new people who can easily be confused by the mention of HEAD, hoping that new people, while they are prone to confusion about "HEAD", won't be dealing with detached HEAD.

Much later, --track was tacked on, but this is a very different concept. A branch you are creating can be marked to always merge from another branch (be it local or remote). The branch creation command syntax conflates these two different concepts, because they are often used together.

It is incorrect to say that <start-point> needs to be explicitly spelled out. You can detach HEAD to point at the tip of a remote branch, and then say "git branch new" to create a branch "new".

	git checkout origin/next
        git branch new

It will start that branch at the tip of the remote branch (which points at the same commit as your HEAD points at).

The resulting "new" branch won't be tracking the remote branch (iow, you are correct if you said that a remote branch won't be tracked without being named). But the branch still starts at the commit HEAD points at, which is the same as the one at the tip of the remote branch in the above example.

In git, a branch is a label that attaches to an existing commit [*1*] and because of that, you cannot go from a commit to a branch (a commit can be part of any number of branches). Detached HEAD points only at a commit without being associated with any particular branch, either local or remote. And because you cannot go from a commit to a branch, "git branch new" can start the new branch at the correct commit, but it cannot make it track the remote branch you detached your HEAD at.

I think _you_ understand all of the above, but because you (and probably the documentation updates made after --track was introduced) are confused about the two distinct concepts, the patch talks about the detached HEAD in the description of <start-point>, which is _not_ affected by the detachedness of the HEAD. What needs clarification is --tracked part.

Perhaps the attached patch may be an improvement.

But having to explain "checking out anything but a local branch will make you not on _any_ branch" (possibly repeating my explanation above as well) every time we say "this command uses the current branch in this way" feels very wrong. The description should make it clear what we mean by "the current branch" --- and things like "when your HEAD is detached, you are not on any branch and by definition you do not have 'the current branch'" should be best left in the introductory "concepts" document that is a required reading before the reader goes to descriptions of individual commands.

This is a tangent, not directly related to your patch, but I see that the conflation between start-point and branch tracking made some things very cumbersome to do.

Suppose you came up with a neat idea, and wanted to experiment first, because you did not know if the idea will pan out. You detach at my 'next', hack a while, and ended up with something wonderful. Because you do not want to lose the work you did, you create a branch there:

	git checkout origin/next ;# detach!
        hack hack; git commit
        git branch my-hack-on-next

The start point of the new branch is the commit you recorded your hacks with. And it does not track origin/next, as detached HEAD is not associated with any particular branch. But as far as I can see, there is no easy way to retroactively mark this new branch _track_ origin/next, short of doing the "git config" yourself.

[Footnote]

*1* Technically speaking, there is an exception. Immediately after "git init" in an empty repository, HEAD says you are _on_ master branch that does not exist yet.

-- >8 --

 Documentation/git-branch.txt |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)

Junio C Hamano wrote:

I indeed confused these concepts and I think your patch makes the documentation clearer here

 / Martin

Martin Nordholts venit, vidit, dixit 18.06.2009 08:04:

I think your usage of "start-point" is a bit unfortunate. What's a start-point? It's the commit where a branch forks off, or more precisely: the commit which the new branch's head is set to initially.

So, the start-point is never a branch! Or else it would be a "moving target".

If you specify the start-point using a branch name it's really the branch's current head which is used as the start-point.

BUT: If you specify the start-point using a branch name the DWIMery can
kick in and figure out a good default for the upstream branch (see --track).

Michael