Re: Terminology question about remote branches.

From: David Kastrup <dak@gnu.org>
Date: Aug 4, 2007, 12:36 UTC
Message-ID: <85tzrfh3yg.fsf@lola.goethe.zz>
In-Reply-To: <20070804120243.GB9716@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 6 quoted lines

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

Show 21 quoted lines

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

Show 8 quoted lines

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

Show 13 quoted lines

> 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