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.
