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

From: Andreas Ericsson <[email-masked]>
Date: Wed, 14 Nov 2007 02:02:52 +0100

Junio C Hamano wrote:
> Andreas Ericsson <[email-masked]> 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.
> 

I'd skip "after you built your own changes ..." and let it go at
that. Will amend. Thanks.

> 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";
> 

I'd like to insert the significant dash there. remote-tracking vs
remote tracking. It solves the one ambiguity with it, and would
finally make it clear and consistent almost however it's used.

>  * 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;
> 

"private tracking branch"? Nah...

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

"remote-repo branch" perhaps? The universe doesn't exactly toll its
bells in approval at that, but at least it's not ambiguous.

I've seen it written as "remote tracking branch" on irc a few times.
It causes 10 minutes of confusion where no-one's sure what anyone
else means. With the dash in there, there's no room for ambiguity.

-- 
Andreas Ericsson                   [email-masked]
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231