Re: [PATCH v1] config/branch: state that <name>.merge is the remote ref

[Philip Oakley <philipoakley@iee.email>]

Hi Junio,
On 19/10/2019 00:11, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> writes:
>
>> branch.<name>.merge::
>>      Defines, for the local branch <name>, the upstream branch ref
>>      _on the remote_ (as given by branch.<name>.remote).
>>      The upstream ref may be different from the local branch ref.
>>
>> optionally s/different from/ same as/ ?
> That "optionally" part is exactly why I said "upstream and remote
> tracking names may or may not differ is irrelevant information".
I think we misunderstand each other again. That very potential 
difference, no matter which way described, was the point at hand - that 
is we are talking about refs at different places.

If we have (quite typically) that merge config indicating that we wish 
to merge refs/heads/master with refs/heads/master then it looks like a 
no-op. They are both the same ref (by name / character sequence). 
Without the extra knowledge that one is local and the other is remote 
then the mental model confusion in the reader continues. The 
'optionally' offer was about choosing the best way of coercing the 
reader into considering the alternate viewpoint. Sometime things  need 
to explained both ways, so that at least one will register.

It could be argued that the merge ref should have been 
`refs/remotes/origin/master` (for that typical following case), but it 
isn't (IIUC because of historic backward compatibility), which would 
have at least avoided the local  v remote conundrum.

All that said, I ended up going with your suggested text anyway ;-)
>>>       The name of the branch at the remote `branch.<name>.remote` that
>>>       is used as the upstream branch for the given branch.  It tells
>>>       `git fetch`, etc., which branch to merge and ...
>>>
>> If this, should we also say it (the key value) is that of the upstream
>> branch _ref_?
> Yeah, that makes it clear that readers should not write "master" and
> use "refs/heads/master" instead.  It may even be more (technically)
> correct to say just "ref" without branch (this ref does not have to
> be a branch at the remote repository at all).  I am not sure if we
> want to go that far to make it more correct and also make it hint
> that using a non-branch ref is a valid configuration to readers, but
> I agree it is a good idea to avoid saying "name" (which implies
> that "master" is OK, which is not).
I'd agree. I'll think about the simplified ref comment.

P.