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

[Thore Husfeldt <thore.husfeldt@gmail.com>]

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. 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,” and “connected to them” could be more concrete.)

I appreciate that this misunderstanding looks ridiculous in hindsight—it does to me, today. Luckily, I kept a copy of my old brain in thore/oldbrain and try to not fetch to it.

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

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.