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

[Jakub Narebski <jnareb@gmail.com>]

Thore Husfeldt <thore.husfeldt@gmail.com> writes:
> On 23 Oct 2010, at 18:31, Matthieu Moy wrote:

> > 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". It’s 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.

> The Pro Git book goes as far as saying "they’re 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).

> 
> I realise that it would be more constructive for me to suggest a
> concrete improvement, but I’m 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 Bob’s master

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

-- 
Jakub Narebski
Poland
ShadeHawk on #git