Re: [PATCH v2 2/3] for-each-ref: let upstream/push optionally remote ref name

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 14, 2017, 02:08 UTC
Message-ID: <xmqqinfiv5u2.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171013163923.GA5598@alpha.vpn.ikke.info>

Kevin Daudt <me@ikke.info> writes:

Show 19 quoted lines

> On Thu, Oct 05, 2017 at 02:19:15PM +0200, Johannes Schindelin wrote:
>> From: J Wyman <jwyman@microsoft.com>
>> [..] 
>> 
>> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
>> index 39f50bd53eb..22767025850 100644
>> --- a/Documentation/git-for-each-ref.txt
>> +++ b/Documentation/git-for-each-ref.txt
>> @@ -142,8 +142,9 @@ upstream::
>>  	encountered. Append `:track,nobracket` to show tracking
>>  	information without brackets (i.e "ahead N, behind M").
>>  +
>> -Also respects `:remotename` to state the name of the *remote* instead of
>> -the ref.
>> +Also respects `:remotename` to state the name of the *remote* instead
>> +of the ref, and `:remoteref` to state the name of the *reference* as
>> +locally known by the remote.
>
> What does "locally known by the remote" mean in this sentence?

Good question. I cannot offhand offer a better and concise phrasing, but I think can explain what it wants to describe ;-).

For a local branch we have (say, 'topic'), there may be different things outside this repository that regularly interact with it.

We may update 'topic' with work others did, by

	git checkout topic && git pull

without any extra command line argument to "git pull". We are pulling from the 'upstream' of the 'topic', which is a branch in a remote repository, and the (nick)name of the remote is :remotename. When we do this pull, we would grab one of the branches the remote has and merge it into our 'topic'. IOW, when the above command line is written in longhand, the "git pull" step may look like this [*1*]:

	git pull origin devel

if we were building on top of the 'devel' branch at the 'origin' remote. The full refname of that branch, 'refs/heads/devel', is :remoteref, and that is the reference locally known to the 'origin' remote.

The "locally known by the remote" is an attempt by the patch authors to stress the fact that the result is not refs/remotes/origin/devel (which is where _you_ would keep a local copy of that reference in this repository).

Two other things outside this repository that interact with 'topic' are where the result of our work is pushed out to, which is a branch at the 'push' remote.

[Footnotes]

*1* Modulo the details of other refs fetched that are unrelated to
    the resulting merge and local copies stored as remote-tracking
    branches in this repository.