On Sat, 04 Aug 2007 12:55:43 +0200
David Kastrup <dak@gnu.org> wrote:

quoted text
> I am trying to dig through man-pages and user manual and trying to
> match them with reality.  I seem to have a hard time.  My current
> understanding (which definitely differs from the documented state) is
> that there are two types of branches, local and remote branches, and
> both types of branches can be remote-tracking (it may not be possible
> to have a non-remote-tracking remote branch, though).
>
> A local branch is one with a local branch head.  In contrast, checking
> out a remote branch, while possible, leaves one with a detached head.

Yes.

quoted text
> "remote-tracking" basically means that git-pull will update the branch
> according to changes in the remote repository.

To be clear, it's the job of git-fetch to update remote-tracking branches
with any changes found in the remote repository.  Git-pull runs git-fetch
and then runs a git-merge to update the currently-checked-out branch.

When this happens, git-merge must decide which remote-tracking-branch
to merge into the currently checked out local branch.  You can set which
remote-tracking-branch will be selected in this situation with
the --track option.

So assuming a remote-repo has two branches "master" and "branchX":

   git clone remote-repo

will give us two remote-branch (AKA remote-tracking-branches) of
"origin/master" and "origin/branchX".  So:

   git branch --track mylocalbranch origin/branchX
   git checkout mylocalbranch

Creates a local branch named "mylocalbranch" that by default will
merge in any changes found in the remote-tracking branch
"origin/branchX".  Thus:

   git pull

First runs git fetch which will update all remote-tracking branches
such as origin/master and origin/branchX.  Then it runs git merge.
Git merge has to decide whether to merge in the changes from
origin/master or origin/branchX.  Because of the --track option used
to setup "mylocalbranch",  "origin/branchX" will be merged.

quoted text
> Creating a branch using git-branch or git-checkout will always create
> a local branch which may or may not be remote-tracking according to
> the --no-track or --track options.

No, a local branch is never a remote-tracking branch; even when created
with a --track option.  The --track option has muddied the terminology
waters a bit and you're not the first to be confused by it.  The
--track selects a branch from the repo to merge by default.

quoted text
> So there are basically three types of branches in a repository that I
> can see:
> 
> local branch, not remote-tracking
> local branch, remote-tracking
> remote branch, remote-tracking
> 
> The way to add a remote branch basically is not via git-branch or
> git-checkout -b (those always create local branches), but by editing
> .git/config.
> 
> Is this understanding correct or did I get things completely wrong?
> Because there is little sense in myself working on changing the
> documentation if I have not understood the situation.

Functionally, your understanding is correct.  But it helps when you
understand that remote-branches are the "real" remote-tracking-branches.
You don't commit to them locally, they are essentially read-only copies
of exactly what is happening in a remote repository.

A local --track branch, is one that merges changes from the proper
remote-tracking-branch, and is also a place where you can commit your
own work.

quoted text
> Also, the documentation currently uses "remote-tracking"
> interchangeably for "local branch, remote-tracking" and "remote
> branch, remote-tracking", at some times claiming that one can locally
> switch to a "remote-tracking" branch, at other times not.

A remote branch and a remote-tracking branch are the same thing.
Strictly speaking a local branch is never a remote-tracking-branch
although the "--track" option makes that harder to explain.

quoted text
> So the terminology seems fuzzy at the moment, and my attempt to clear
> it up might not be the preferred way of doing it.

Yeah, the documentation could use some fine tuning.

Sean
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html