{"thread":{"id":"52045","subject":"[PATCH v1] config/branch: state that <name>.merge is the remote ref","startedAt":"2019-10-16T11:28:55Z","lastAt":"2019-10-19T15:19:09Z","messageCount":6,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"384175","messageId":"20191016112822.1701-1-philipoakley@iee.email","threadId":"52045","inReplyTo":null,"subject":"[PATCH v1] config/branch: state that <name>.merge is the remote ref","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2019-10-16T11:28:22Z","receivedAt":"2019-10-16T11:28:55Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The branch.<name>.merge value typically looks just like a\nlocal ref. Tell the reader it is the ref name at the remote,\nwhich may be different.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.email>\n---\n\nThis confusion had me scratching my head for many minutes recently.\nA simple clarification would avoid such mental model errors.\n\n Documentation/config/branch.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt\nindex a592d522a7..3bfe4f81d3 100644\n--- a/Documentation/config/branch.txt\n+++ b/Documentation/config/branch.txt\n@@ -53,7 +53,9 @@ branch.<name>.pushRemote::\n \n branch.<name>.merge::\n \tDefines, together with branch.<name>.remote, the upstream branch\n-\tfor the given branch. It tells 'git fetch'/'git pull'/'git rebase' which\n+\tfor the given branch. It defines the branch name _on the remote_,\n+\twhich may be different from the local branch name.\n+\tIt tells 'git fetch'/'git pull'/'git rebase' which\n \tbranch to merge and can also affect 'git push' (see push.default).\n \tWhen in branch <name>, it tells 'git fetch' the default\n \trefspec to be marked for merging in FETCH_HEAD. The value is\n-- \n2.23.0.windows.1.21.g947f504ebe8.dirty\n\n"},{"id":"384334","messageId":"xmqqwod26dp7.fsf@gitster-ct.c.googlers.com","threadId":"52045","inReplyTo":"20191016112822.1701-1-philipoakley@iee.email","subject":"Re: [PATCH v1] config/branch: state that <name>.merge is the remote ref","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-10-18T01:32:20Z","receivedAt":"2019-10-18T01:32:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n>  branch.<name>.merge::\n>  \tDefines, together with branch.<name>.remote, the upstream branch\n> -\tfor the given branch. It tells 'git fetch'/'git pull'/'git rebase' which\n> +\tfor the given branch. It defines the branch name _on the remote_,\n> +\twhich may be different from the local branch name.\n\nWhile I do agree with the goal of make things more clear, I'd avoid\nbeing overly redundant and giving irrelevant information (e.g. the\ncopy you have locally may be made under arbitrary name that is\ndifferent from the name used at the remote).  After all, the users\ndo not even need to know about the remote-tracking branch to\nunderstand this naming mechanism.\n\nPerhaps something along this line instead:\n\n    The name of the branch at the remote `branch.<name>.remote` that\n    is used as the upstream branch for the given branch.  It tells\n    `git fetch`, etc., which branch to merge and ...\n\n"},{"id":"384412","messageId":"c96f4dbd-ebc6-b743-716e-e1e17333c06b@iee.email","threadId":"52045","inReplyTo":"xmqqwod26dp7.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v1] config/branch: state that <name>.merge is the remote ref","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2019-10-18T20:53:02Z","receivedAt":"2019-10-18T20:53:06Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 18/10/2019 02:32, Junio C Hamano wrote:\n> Philip Oakley <philipoakley@iee.email> writes:\n>\n>>   branch.<name>.merge::\n>>   \tDefines, together with branch.<name>.remote, the upstream branch\n>> -\tfor the given branch. It tells 'git fetch'/'git pull'/'git rebase' which\n>> +\tfor the given branch. It defines the branch name _on the remote_,\n>> +\twhich may be different from the local branch name.\n> While I do agree with the goal of make things more clear, I'd avoid\n> being overly redundant and giving irrelevant information (e.g. the\n> copy you have locally may be made under arbitrary name that is\n> different from the name used at the remote).  After all, the users\n> do not even need to know about the remote-tracking branch to\n> understand this naming mechanism.\nI'd argue that the user has to know about the branch <name> to even get \nhere,\nand that the key value can be confusing (been there!), so improving the \nunderstanding\nwas the aim.\n\nThat said, tedious repetition should be avoided, so I'll look to reword \nit while still retaining the emphasis. Perhaps:\n\nbranch.<name>.merge::\n     Defines, for the local branch <name>, the upstream branch ref\n     _on the remote_ (as given by branch.<name>.remote).\n     The upstream ref may be different from the local branch ref.\n\noptionally s/different from/ same as/ ?\n\n>\n> Perhaps something along this line instead:\n>\n>      The name of the branch at the remote `branch.<name>.remote` that\n>      is used as the upstream branch for the given branch.  It tells\n>      `git fetch`, etc., which branch to merge and ...\n>\nIf this, should we also say it (the key value) is that of the upstream \nbranch _ref_?\n\nHmm, *thinks*, I think I'm being swayed by your version. Update to follow.\n\nPhilip\n"},{"id":"384413","messageId":"20191018205935.2529-1-philipoakley@iee.email","threadId":"52045","inReplyTo":"c96f4dbd-ebc6-b743-716e-e1e17333c06b@iee.email","subject":"[PATCH v2] config/branch: state that <name>.merge is the remote ref","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2019-10-18T20:59:35Z","receivedAt":"2019-10-18T20:59:45Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The branch.<name>.merge value typically looks just like a\nlocal ref. Tell the reader it is the ref name at the remote,\nwhich may be different.\n\nSigned-off-by: Philip Oakley <philipoakley@iee.email>\n---\n Documentation/config/branch.txt | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt\nindex a592d522a7..cdc19edaaf 100644\n--- a/Documentation/config/branch.txt\n+++ b/Documentation/config/branch.txt\n@@ -52,8 +52,10 @@ branch.<name>.pushRemote::\n \toption to override it for a specific branch.\n \n branch.<name>.merge::\n-\tDefines, together with branch.<name>.remote, the upstream branch\n-\tfor the given branch. It tells 'git fetch'/'git pull'/'git rebase' which\n+\tThe name of the branch ref at the remote `branch.<name>.remote`\n+\tthat is used as the upstream branch for the given branch <name>.\n++\n+\tIt tells 'git fetch'/'git pull'/'git rebase' which\n \tbranch to merge and can also affect 'git push' (see push.default).\n \tWhen in branch <name>, it tells 'git fetch' the default\n \trefspec to be marked for merging in FETCH_HEAD. The value is\n-- \n2.23.0.windows.1.21.g947f504ebe8.dirty\n\n"},{"id":"384438","messageId":"xmqq8sphodi6.fsf@gitster-ct.c.googlers.com","threadId":"52045","inReplyTo":"c96f4dbd-ebc6-b743-716e-e1e17333c06b@iee.email","subject":"Re: [PATCH v1] config/branch: state that <name>.merge is the remote ref","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-10-18T23:11:29Z","receivedAt":"2019-10-18T23:11:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n> branch.<name>.merge::\n>     Defines, for the local branch <name>, the upstream branch ref\n>     _on the remote_ (as given by branch.<name>.remote).\n>     The upstream ref may be different from the local branch ref.\n>\n> optionally s/different from/ same as/ ?\n\nThat \"optionally\" part is exactly why I said \"upstream and remote\ntracking names may or may not differ is irrelevant information\".\n\n>>      The name of the branch at the remote `branch.<name>.remote` that\n>>      is used as the upstream branch for the given branch.  It tells\n>>      `git fetch`, etc., which branch to merge and ...\n>>\n> If this, should we also say it (the key value) is that of the upstream\n> branch _ref_?\n\nYeah, that makes it clear that readers should not write \"master\" and\nuse \"refs/heads/master\" instead.  It may even be more (technically)\ncorrect to say just \"ref\" without branch (this ref does not have to\nbe a branch at the remote repository at all).  I am not sure if we\nwant to go that far to make it more correct and also make it hint\nthat using a non-branch ref is a valid configuration to readers, but\nI agree it is a good idea to avoid saying \"name\" (which implies\nthat \"master\" is OK, which is not).\n\nThanks.\n\n\n"},{"id":"384453","messageId":"1060efbc-8776-b14c-a1a6-36c03c917059@iee.email","threadId":"52045","inReplyTo":"xmqq8sphodi6.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v1] config/branch: state that <name>.merge is the remote ref","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2019-10-19T15:19:00Z","receivedAt":"2019-10-19T15:19:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\nOn 19/10/2019 00:11, Junio C Hamano wrote:\n> Philip Oakley <philipoakley@iee.email> writes:\n>\n>> branch.<name>.merge::\n>>      Defines, for the local branch <name>, the upstream branch ref\n>>      _on the remote_ (as given by branch.<name>.remote).\n>>      The upstream ref may be different from the local branch ref.\n>>\n>> optionally s/different from/ same as/ ?\n> That \"optionally\" part is exactly why I said \"upstream and remote\n> tracking names may or may not differ is irrelevant information\".\nI think we misunderstand each other again. That very potential \ndifference, no matter which way described, was the point at hand - that \nis we are talking about refs at different places.\n\nIf we have (quite typically) that merge config indicating that we wish \nto merge refs/heads/master with refs/heads/master then it looks like a \nno-op. They are both the same ref (by name / character sequence). \nWithout the extra knowledge that one is local and the other is remote \nthen the mental model confusion in the reader continues. The \n'optionally' offer was about choosing the best way of coercing the \nreader into considering the alternate viewpoint. Sometime things  need \nto explained both ways, so that at least one will register.\n\nIt could be argued that the merge ref should have been \n`refs/remotes/origin/master` (for that typical following case), but it \nisn't (IIUC because of historic backward compatibility), which would \nhave at least avoided the local  v remote conundrum.\n\nAll that said, I ended up going with your suggested text anyway ;-)\n>>>       The name of the branch at the remote `branch.<name>.remote` that\n>>>       is used as the upstream branch for the given branch.  It tells\n>>>       `git fetch`, etc., which branch to merge and ...\n>>>\n>> If this, should we also say it (the key value) is that of the upstream\n>> branch _ref_?\n> Yeah, that makes it clear that readers should not write \"master\" and\n> use \"refs/heads/master\" instead.  It may even be more (technically)\n> correct to say just \"ref\" without branch (this ref does not have to\n> be a branch at the remote repository at all).  I am not sure if we\n> want to go that far to make it more correct and also make it hint\n> that using a non-branch ref is a valid configuration to readers, but\n> I agree it is a good idea to avoid saying \"name\" (which implies\n> that \"master\" is OK, which is not).\nI'd agree. I'll think about the simplified ref comment.\n\nP.\n\n\n"}]}