Kevin Daudt <me@xxxxxxxxx> writes:
> On Thu, Oct 05, 2017 at 02:19:15PM +0200, Johannes Schindelin wrote:
>> From: J Wyman <jwyman@xxxxxxxxxxxxx>
>> [..]
>>
>> 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.
