Re: [Newbie] How to *actually* get rid of remote tracking branch?

[Junio C Hamano <gitster@pobox.com>]

Andreas Ericsson <ae@op5.se> writes:

> I've got half a patch ready to change all occurrences of anything but
> "remote-tracking branch" to that self-same description. This is what
> I've got in Documentation/glossary.txt so far:
>
> [[def_remote_tracking_branch]]remote-tracking branch:
>    A "remote-tracking branch" is a branch set up to track the
>    state of a branch in a remote repository which the user has named.
> These branches follow exactly the same rules as the branches which
>    reside in the remote repository, except that they are manipulated
>    by `git fetch` instead of `git push`. That is, they can only be
>    updated if the update would result in a  <<def_fastforward,fast
> forward>>, or if the user supplies the  '--force' option.  They cannot
> be checked out or committed to by users, but serve
>    solely as local reference-pointers to their corresponding branches
>    in the remote repository.
>    The most common example of a remote-tracking branch is origin/master.

Please try to read it as if it were an entry in a glossary.
The sentence "... follow exactly the same rules as ..." was
"Huh?" to me.  "rules?  what rules?  the set of valid characters
in their names?"

When branch 'foo' from remote is tracked with the standard layout
(post 1.3.0) it is copied to refs/remotes/origin/foo and people
often fork their local branch refs/heads/foo to build on top.
The use of the word "corresonding" feels a bit confusing,
because you can arguably say refs/heads/foo at remote
corresopnds to refs/heads/foo in your repository.

I'd drop "These branches follow ... the '--force' option.  "
from the above.  The rules on how they are updated are
irrelevant, before the reader understands what they are for.
How about this?

    A "remote tracking branch" remembers which commit a branch
    in the remote repository was pointing at last time you
    checked.  It cannot be checked out or committed because its
    purpose is to serve as a local reference point after you
    built your own changes on top of it in your local branch
    forked from it.  The most common example of a remote
    tracking branch is "origin/master", which tracks the
    "master" branch of the "origin" remote.

BTW, when you have this data-flow (probably typical in a shared
repository workflow):

    Remote repository               Your repository

    refs/heads/foo -------(A)------> refs/remotes/origin/foo
         ^                                |
         |                               (B)
         |                                |
         |                                V
         `-------------(C)---------- refs/heads/foo

         (A) "git fetch" with remote.origin.fetch configuration
             set to +refs/heads/*:refs/remotes/origin/* keeps
             your refs/remotes/origin/foo up-to-date with their
             refs/heads/foo

         (B) "git merge origin/foo" while on "foo" branch (there
             are few shorthands like "git pull origin foo" while
             on "foo" branch.  If you say "git branch --track
             foo origin/foo", then running "git pull" without
             parameter while on "foo" branch).

         (C) "git push origin foo".

 * Everybody seems to agree that "refs/remotes/origin/foo" is
   called a "remote tracking branch";

 * Your refs/heads/foo follows and builds on top of 'foo' branch
   at the remote.  Some people errorneously call it "tracking"
   but that is because we do not have a good term for it;

 * There is no good name for "refs/heads/foo at the remote".  We
   always say "the remote branch you follow" (or "track").