Re: [PATCH 09/10] user-manual.txt: explain better the remote(-tracking) branch terms

From: Jakub Narebski <jnareb@gmail.com>
Date: Oct 24, 2010, 23:32 UTC
Message-ID: <m3bp6jjhhm.fsf@localhost.localdomain>
In-Reply-To: <9A09AA7C-BAE2-4571-8453-17CB3F3256D4@gmail.com>

Thore Husfeldt <thore.husfeldt@gmail.com> writes:

> On 23 Oct 2010, at 18:31, Matthieu Moy wrote:

Show 21 quoted lines

> > Documentation/user-manual.txt |    9 +++++++++
> > 1 files changed, 9 insertions(+), 0 deletions(-)
> > 
> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> > index d70f3e0..02126f1 100644
> > --- a/Documentation/user-manual.txt
> > +++ b/Documentation/user-manual.txt
> > @@ -359,6 +359,11 @@ $ git branch -r
> >   origin/todo
> > ------------------------------------------------
> > 
> > +In this case, "origin" is called a remote repository, or "remote" for
> > +short. The branches of this repository are called "remote branches"
> > +from our point of view, and Git will maintain a copy of these
> > +branches, called "remote-tracking branches" in the local repository.
> 
> No. Git does not "maintain a copy of [the remote]
> branches". Its exactly one of the pitfalls I fell into: that
> Git, automagically, puts the *current* state of the remote branch
> into remote/branchname, or at least updates it behind my back
> whenever it gets the chance.

So you don't like the word "maintain" here, is it? Perhaps "keep" instead of "maintain" would be a better word?

I guess that we can also add the following explanation:

  Those "remote-tracking branches" would be updated to the state of tracked
  branches in remote repository on fetch.

Show 7 quoted lines

> The Pro Git book goes as far as saying "theyre moved
> automatically whenever you do any network communication," which
> is extremely misleading. (And then it goes on: "Remote branches
> act as bookmarks to remind you where the branches on your remote
> repositories were the last time you connected to them." This is a
> good way of saying it, except that "remote branches" should be
> "remote-tracking branches,"

Right

> and "connected to them" could be more concrete.)

I guess that the word 'connected' is used here to avoid repetition. But it is a bit unprecise: "git remote show <remote>" connects to remote repository but does not update remote-tracking branches.

> Also note that the two following lines in user-manual.txt are plain
> wrong ("You cannot check out these remote-tracking branches, but you
> can examine them on a branch of your own, just as you would a tag").

This is simply outdated information, predating invention of detached HEAD (also known as anonymous / unnamed branch). They are not _that_ wrong, as you don't checkout a remote-tracking branch: you checkout _state_ of remote tracking branch, creating unnamed branch for that (state marked in git-branch output as "(no branch)"). But I guess it is too fine distinction (splitting hairs).

Show 5 quoted lines

> 
> I realise that it would be more constructive for me to suggest a
> concrete improvement, but Im not quite there yet. I would really
> like to see a good conceptualisation, with strong, versatile verbs,
> of the relationships between bobsstuff bob/master and Bobs master

Nevertheless your contributions, even those in the form of pointing errors and inconsistences, are very welcome.

-- 
Jakub Narebski
Poland
ShadeHawk on #git