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

Thore Husfeldt [off-list ref] writes:

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

quoted

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