Re: Terminology question about remote branches.

[David Kastrup <dak@gnu.org>]

Jeff King <peff@peff.net> writes:

> On Sat, Aug 04, 2007 at 12:55:43PM +0200, David Kastrup wrote:
>
>> 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, if by "remote branch" you mean a "remote tracking branch".

Jeff, I actually have no _clue_ what I "mean" with respect to the
established git terminology because I can't reconcile the
documentation's use of words with my meagre understanding of the
technical processes involved.

So I can't even tell you whether "by remote branch I mean a remote
tracking branch".

>> "remote-tracking" basically means that git-pull will update the
>> branch according to changes in the remote repository.
>
> A "remote tracking branch" is a branch in refs/remotes/* that is
> updated by _git-fetch_ (which is in turn called by git-pull) to
> track a remote's position of a branch.
>
> A local branch which tracks a remote branch (I don't recall seeing
> the phrase "remote-tracking" -- where did this come from?) has the
> correct magic in .git/config to pull from a specific remote branch
> when 'git-pull' is given without arguments.
>
>> 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.
>
> Yes, although again, I think calling it a "remote-tracking branch"
> to mean "a local branch that tracks a remote branch" is confusingly
> similar to the more common "remote tracking branch" to mean "a
> branch in refs/remotes that track's a remote repository's idea of a
> branch".

Well, of _course_ it is confusingly similar.  After all, I am posting
this question because I _am_ confused!  And I am trying to both clear
up my confusion as well as get an idea how to fix the documentation to
be less confusing.

>> 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
>
> No, the remote branch is not remote-tracking in the sense that you
> defined above; it is not meant to be pulled into.

Sigh.  But it is cached and updated locally in some manner when
pulling, isn't it?  I can diff against it.

> I think you are confused by two uses of the word "track". In one
> case, we mean that git-fetch will remember the remote's idea of a
> branch in refs/remotes/<remote>/<branch>. In another, we mean that a
> local branch will default to pulling from a particular
> (remote,branch) combination.
>
>> So the terminology seems fuzzy at the moment, and my attempt to
>> clear it up might not be the preferred way of doing it.
>
> Yes, it is very fuzzy. Using "track" for the concept of a local
> branch defaulting to a particular (remote,branch) pair for git-pull
> is, I think, more recent and less used. If there were another term
> for this, it might be more clear.

It is not just git-pull.  I don't get the fine lines between "remote",
"remote tracking" and the respective details in either the user manual
or the manual pages of branch-related commands.

And it's actually worse after your explanations.  Previously I
imagined to have a chance to figure this out on my own, by trying to
abstract from what I see happening when using the various commands.

Now I think that I basically have no chance figuring this out on my
own sufficiently well to be able to improve the documentation.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum