{"thread":{"id":"37277","subject":"[PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","startedAt":"2014-08-02T15:46:22Z","lastAt":"2014-08-05T18:19:13Z","messageCount":8,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":1},"messages":[{"id":"247174","messageId":"1406994383-5076-1-git-send-email-philipoakley@iee.org","threadId":"37277","inReplyTo":null,"subject":"[PATCH v2 0/1] doc: format-patch","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-02T15:46:22Z","receivedAt":"2014-08-02T15:46:22Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Following the discussion at [1], I decided that while I felt the\ndocumentation changes were OK, the commit message need more explanation\nto cover the points raised in the discussion. Thus the only changes\nare to the commit message.\n\nIn addition I'll separately cover the point raised about the DWIM\ndescription in gitrevisions(7). I'd also picked up that \naren't covered by it either.\n\nPhilip\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/254652\n\nPhilip Oakley (1):\n doc: format-patch: don't use origin as a branch name\n\n Documentation/git-format-patch.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\n-- \n1.9.4.msysgit.0\n"},{"id":"247173","messageId":"1406994383-5076-2-git-send-email-philipoakley@iee.org","threadId":"37277","inReplyTo":"1406994383-5076-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-02T15:46:23Z","receivedAt":"2014-08-02T15:46:23Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch used\n'origin' as the upstream branch name. That name is now used as the nominal\nname for the upstream remote.\n\nWhile 'origin' would be DWIMmed (do what I mean) to be that remote's\nprimary branch, do not assume the reader is ready for such magic.\n\nLikewise, do not use 'origin/master' which may not be up to date with the\nremote, nor reflect the reader's master branch. The patch series should be\nrelative to the reader's view of 'git show-branch HEAD master'.\n\nUse the more modern 'master' as the reference branch name.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-format-patch.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex c0fd470..b0f041f 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -523,25 +523,25 @@ $ git format-patch -k --stdout R1..R2 | git am -3 -k\n ------------\n \n * Extract all commits which are in the current branch but not in the\n-origin branch:\n+master branch:\n +\n ------------\n-$ git format-patch origin\n+$ git format-patch master\n ------------\n +\n For each commit a separate file is created in the current directory.\n \n-* Extract all commits that lead to 'origin' since the inception of the\n+* Extract all commits that lead to 'master' since the inception of the\n project:\n +\n ------------\n-$ git format-patch --root origin\n+$ git format-patch --root master\n ------------\n \n * The same as the previous one:\n +\n ------------\n-$ git format-patch -M -B origin\n+$ git format-patch -M -B master\n ------------\n +\n Additionally, it detects and handles renames and complete rewrites\n-- \n1.9.4.msysgit.0\n"},{"id":"247215","messageId":"xmqq38dctcmz.fsf@gitster.dls.corp.google.com","threadId":"37277","inReplyTo":"1406994383-5076-2-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-04T16:58:44Z","receivedAt":"2014-08-04T16:58:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch used\n> 'origin' as the upstream branch name. That name is now used as the nominal\n> name for the upstream remote.\n>\n> While 'origin' would be DWIMmed (do what I mean) to be that remote's\n> primary branch, do not assume the reader is ready for such magic.\n\nGood thinking.\n\n> Likewise, do not use 'origin/master' which may not be up to date with the\n> remote, nor reflect the reader's master branch. The patch series should be\n> relative to the reader's view of 'git show-branch HEAD master'.\n\nThis however is backwards, no? The history on 'origin/master' may\nnot be up-to-date in the sense that if you run 'git fetch' you might\nget more, but it absolutely is up-to-date in the sense that it shows\nwhat the origin has to the best of your repository's current\nknowledge.\n\nCompared to that, what the user's local 'master' has is much less\nrelevant. For one thing, if a more recent commit that is on the\nremote repository is missing on 'origin/master' because you haven't\nfetched recently, by definition that commit will not be on your\n'master' either, so you have the same staleness issue to the exact\ndegree. Even worse, when you are developing a topic to upstream, it\nis a good practice to merge your topic to your own 'master' to check\nit with the wider project codebase that is more recent than where\nyour topic earlier forked from, and it makes little sense to tell\n'exclude what I have on my master' to format-patch when extracting\nchanges to upstream out of such a topic. You send what the other\nside has, not what you do not have on your local 'master' branch.\n\n> Use the more modern 'master' as the reference branch name.\n\nThere is nothing 'modern' in 'master'.\n\nI think the original description was written before we switched to\nthe separate remote layout. What is in 'refs/remote/origin/master'\nthese days was stored and updated at 'refs/heads/origin' and no\nother branch from the remote repository was tracked back then. The\nchanges to be upstreamed are output by grabbing what are not in\n'origin', whose modern equivalent is 'origin/master'.\n\nIn short, if your patch were s|origin|origin/master|, instead of\ns|origin|master|, that would be an adjustment to the more modern\nworld that is still faithful to the intent of the original.\n\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/git-format-patch.txt | 10 +++++-----\n> 1 file changed, 5 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index c0fd470..b0f041f 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -523,25 +523,25 @@ $ git format-patch -k --stdout R1..R2 | git am -3 -k\n> ------------\n> \n> * Extract all commits which are in the current branch but not in the\n> -origin branch:\n> +master branch:\n> +\n> ------------\n> -$ git format-patch origin\n> +$ git format-patch master\n> ------------\n> +\n> For each commit a separate file is created in the current directory.\n> \n> -* Extract all commits that lead to 'origin' since the inception of the\n> +* Extract all commits that lead to 'master' since the inception of the\n> project:\n> +\n> ------------\n> -$ git format-patch --root origin\n> +$ git format-patch --root master\n> ------------\n> \n> * The same as the previous one:\n> +\n> ------------\n> -$ git format-patch -M -B origin\n> +$ git format-patch -M -B master\n> ------------\n> +\n> Additionally, it detects and handles renames and complete rewrites\n"},{"id":"247220","messageId":"xmqqfvhcru50.fsf@gitster.dls.corp.google.com","threadId":"37277","inReplyTo":"xmqq38dctcmz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-04T18:23:39Z","receivedAt":"2014-08-04T18:23:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Compared to that, what the user's local 'master' has is much less\n> relevant. For one thing, if a more recent commit that is on the\n> remote repository is missing on 'origin/master' because you haven't\n> fetched recently, by definition that commit will not be on your\n> 'master' either, so you have the same staleness issue to the exact\n> degree. Even worse, when you are developing a topic to upstream, it\n\nclarification. I used \"to upstream\" as a verb to mean \"sending the\nwork you did to be applied\".\n\n> is a good practice to merge your topic to your own 'master' to check\n> it with the wider project codebase that is more recent than where\n> your topic earlier forked from, and it makes little sense to tell\n> 'exclude what I have on my master' to format-patch when extracting\n> changes to upstream out of such a topic. You send what the other\n> side has, not what you do not have on your local 'master' branch.\n\nand I have a stupid typo here; obviously I should have typed: You\nsend what the other side \"does not have\".\n"},{"id":"247257","messageId":"F97E9146985F4449A937B9C5CCA1D7F5@PhilipOakley","threadId":"37277","inReplyTo":"xmqq38dctcmz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-04T21:51:52Z","receivedAt":"2014-08-04T21:51:52Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch \n>> used\n>> 'origin' as the upstream branch name. That name is now used as the \n>> nominal\n>> name for the upstream remote.\n>>\n>> While 'origin' would be DWIMmed (do what I mean) to be that remote's\n>> primary branch, do not assume the reader is ready for such magic.\n>\n> Good thinking.\n>\n>> Likewise, do not use 'origin/master' which may not be up to date with \n>> the\n>> remote, nor reflect the reader's master branch. The patch series \n>> should be\n>> relative to the reader's view of 'git show-branch HEAD master'.\n>\n> This however is backwards, no? The history on 'origin/master' may\n> not be up-to-date in the sense that if you run 'git fetch' you might\n> get more, but it absolutely is up-to-date in the sense that it shows\n> what the origin has to the best of your repository's current\n> knowledge.\n\nI still think that the user/reader shouldn't be creating patches based \non wherever someone else had got to, rather it should just be patches \nfrom their own feature branch. However the rest of your argument still \nstands with regard to accidental/unexpected conflicts with other \nupstream work, and the reader should ensure they are already up to \ndate - maybe it needs a comment line to state that.\n\n>\n> Compared to that, what the user's local 'master' has is much less\n> relevant. For one thing, if a more recent commit that is on the\n> remote repository is missing on 'origin/master' because you haven't\n> fetched recently, by definition that commit will not be on your\n> 'master' either, so you have the same staleness issue to the exact\n> degree. Even worse, when you are developing a topic to upstream, it\n> is a good practice to merge your topic to your own 'master' to check\n> it with the wider project codebase that is more recent than where\n> your topic earlier forked from, and it makes little sense to tell\n> 'exclude what I have on my master' to format-patch when extracting\n> changes to upstream out of such a topic. You send what the other\n> side has, not what you do not have on your local 'master' branch.\n>\n>> Use the more modern 'master' as the reference branch name.\n>\n> There is nothing 'modern' in 'master'.\n\nNoted.\n\n>\n> I think the original description was written before we switched to\n> the separate remote layout. What is in 'refs/remote/origin/master'\n> these days was stored and updated at 'refs/heads/origin' and no\n> other branch from the remote repository was tracked back then. The\n> changes to be upstreamed are output by grabbing what are not in\n> 'origin', whose modern equivalent is 'origin/master'.\n>\n> In short, if your patch were s|origin|origin/master|, instead of\n> s|origin|master|, that would be an adjustment to the more modern\n> world that is still faithful to the intent of the original.\n\nI think we would need to clarify that (the intent) for the reader. I'll \nsee what I can do. (suggestion below)\n\n>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/git-format-patch.txt | 10 +++++-----\n>> 1 file changed, 5 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/Documentation/git-format-patch.txt \n>> b/Documentation/git-format-patch.txt\n>> index c0fd470..b0f041f 100644\n>> --- a/Documentation/git-format-patch.txt\n>> +++ b/Documentation/git-format-patch.txt\n>> @@ -523,25 +523,25 @@ $ git format-patch -k --stdout R1..R2 | git \n>> am -3 -k\n>> ------------\n>>\n>> * Extract all commits which are in the current branch but not in the\n>> -origin branch:\n>> +master branch:\n>> +\n>> ------------\n>> -$ git format-patch origin\n>> +$ git format-patch master\n>> ------------\n>> +\n>> For each commit a separate file is created in the current directory.\n\nPerhaps insert \"Note: Your 'master' should be up to date with respect to \n'origin/master' before creating and sending patches upstream to avoid \nunexpected conflicts.\" ?\n\n>>\n>> -* Extract all commits that lead to 'origin' since the inception of \n>> the\n>> +* Extract all commits that lead to 'master' since the inception of \n>> the\n>> project:\n>> +\n>> ------------\n>> -$ git format-patch --root origin\n>> +$ git format-patch --root master\n>> ------------\n>>\n>> * The same as the previous one:\n>> +\n>> ------------\n>> -$ git format-patch -M -B origin\n>> +$ git format-patch -M -B master\n>> ------------\n>> +\n>> Additionally, it detects and handles renames and complete rewrites\n> --\nPhilip \n"},{"id":"247259","messageId":"xmqqa97jrjk2.fsf@gitster.dls.corp.google.com","threadId":"37277","inReplyTo":"F97E9146985F4449A937B9C5CCA1D7F5@PhilipOakley","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-04T22:12:13Z","receivedAt":"2014-08-04T22:12:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> This however is backwards, no? The history on 'origin/master' may\n>> not be up-to-date in the sense that if you run 'git fetch' you might\n>> get more, but it absolutely is up-to-date in the sense that it shows\n>> what the origin has to the best of your repository's current\n>> knowledge.\n>\n> I still think that the user/reader shouldn't be creating patches based\n> on wherever someone else had got to, rather it should just be patches\n> from their own feature branch.\n\nYou forked your topic branch off of the shared project history aka\norigin/master and built some. You may have sent some patches off of\nyour previous work to the upstream, and origin/master may or may not\nhave applied some of them since your topic forked from it. The\npatches you are sending out is from your own topic branch.\n\nYou may be cooking multiple topics, and your local 'master' branch,\nwhich you never push back to 'origin/master', may contain any of\nthese branches. You do not fork off a new topic out of there. Best\ncase, you would fork from 'origin/master'; a bit worse case, you\nhave to fork from another of your topic branch that your new topic\nhas to depend on.\n\nNowhere I am assuming that \"the reader is creating paches based on\nwherever someone else had got to\". Sorry, but I have no idea what\nyou are complaining about.\n\n> However the rest of your argument still\n> stands with regard to accidental/unexpected conflicts with other\n> upstream work, and the reader should ensure they are already up to\n> date - maybe it needs a comment line to state that.\n\nSorry, but I am not sure how much you understood what I wrote.\n\nThe primary reason why 'origin' in the example should be replaced\nwith 'origin/master' is because that is the literal adjustment from\nthe pre-separate-remote world order to today's world order. The\nlocal branch 'origin' (more specifically, 'refs/heads/origin') used\nto be what we used to keep track of 'master' of the upstream, which\nwe use 'refs/remotes/origin/master' these days.\n\n\tSide note: DWIMming origin to remotes/origin/HEAD to\n\tremotes/origin/master was invented to keep supporting this\n\t\"'origin' keeps track of the default upstream\" convention\n\twhen we transitioned from the old world order to\n\tseparate-remote layout.\n\nAnd the reason why 'origin' should not be replaced with 'master' is\nbecause your 'master' may already have patches from the topic you\nare working on, i.e. in your current branch, that the upstream does\nnot yet have. Running \"git format-patch origin/master\" will show\nwhat needs to be accepted by the upstream from you to reproduce your\nwork in full; if you run \"git format-patch master\", it may miss some\nparts that you already have in your local 'master' but not yet in\nthe upstream.\n\nI never talked about conflicts, and I still think that it is\ncompletely outside the scope of these examples. Avoidance of\nconflicts with the work that is already commited to your upstream\nsince you forked is the job for \"rebase\", not \"format-patch\". The\nreason why it is wrong to replace 'origin' in that text with 'master'\ndoes not have anything to do with conflict avoidance.\n\nPuzzled...\n"},{"id":"247262","messageId":"C4E435A5EF324ABCBCC0930A9EB56141@PhilipOakley","threadId":"37277","inReplyTo":"xmqqa97jrjk2.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-04T23:19:32Z","receivedAt":"2014-08-04T23:19:32Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>>> This however is backwards, no? The history on 'origin/master' may\n>>> not be up-to-date in the sense that if you run 'git fetch' you might\n>>> get more, but it absolutely is up-to-date in the sense that it shows\n>>> what the origin has to the best of your repository's current\n>>> knowledge.\n>>\n>> I still think that the user/reader shouldn't be creating patches \n>> based\n>> on wherever someone else had got to, rather it should just be patches\n>> from their own feature branch.\n>\n> You forked your topic branch off of the shared project history aka\n> origin/master and built some. You may have sent some patches off of\n> your previous work to the upstream, and origin/master may or may not\n> have applied some of them since your topic forked from it. The\n> patches you are sending out is from your own topic branch.\n>\n> You may be cooking multiple topics, and your local 'master' branch,\n> which you never push back to 'origin/master', may contain any of\n> these branches. You do not fork off a new topic out of there. Best\n> case, you would fork from 'origin/master'; a bit worse case, you\n> have to fork from another of your topic branch that your new topic\n> has to depend on.\n>\n> Nowhere I am assuming that \"the reader is creating paches based on\n> wherever someone else had got to\". Sorry, but I have no idea what\n> you are complaining about.\n\nI think we are talking at cross purposes. My starting point is that (the \nexamples says that) the reader wants to create a patch series for a \nlocal branch, relative to their branch which they branched \nfrom (e.g. the example, relative to Git, could have been from a 'pu' \npicked up a couple of days earlier, when they'd have said 'git \nformat-patch pu' ;-).\n\nHaving generated their short patch series, and they probably want to \nexpose the series to some collaborator or other for comment, help and \nguidance (or whatever). They may just want to review it themselves. But \nthat choice of what to do with it is surely not part of the format-patch \ndocumentation. So I'm trying to avoid defining a workflow (then or now).\n\nIn the case when the patch series is meant to be ready for being applied \nupstream then all the other considerations apply, but the example \ndoesn't, at least in my eyes, claim to be that.\n\nIIRC I once did make the mistake of using format-patch on a branch (off \npu) I hadn't rebased since fetching and updating the local pu, so it \nproduced a lot of extra patches, but I digress.\n>\n>> However the rest of your argument still\n>> stands with regard to accidental/unexpected conflicts with other\n>> upstream work, and the reader should ensure they are already up to\n>> date - maybe it needs a comment line to state that.\n>\n> Sorry, but I am not sure how much you understood what I wrote.\nThat may be true. I taken your \"not be up-to-date\" to be relative to the \nreal upstream.\n\n>\n> The primary reason why 'origin' in the example should be replaced\n> with 'origin/master' is because that is the literal adjustment from\n> the pre-separate-remote world order to today's world order.\n\nI was trying to avoid a literal adjustment to what I'd perceived as a \npresumed workflow.\n\n> The\n> local branch 'origin' (more specifically, 'refs/heads/origin') used\n> to be what we used to keep track of 'master' of the upstream, which\n> we use 'refs/remotes/origin/master' these days.\n>\n> Side note: DWIMming origin to remotes/origin/HEAD to\n> remotes/origin/master was invented to keep supporting this\n> \"'origin' keeps track of the default upstream\" convention\n> when we transitioned from the old world order to\n> separate-remote layout.\n>\n> And the reason why 'origin' should not be replaced with 'master' is\n> because your 'master' may already have patches from the topic you\n> are working on, i.e. in your current branch, that the upstream does\n> not yet have.\n\nSo this a 'develop on master' view, rather than a 'develop on feature \nbranches' approach? Which could explain the misunderstanding.\n\n> Running \"git format-patch origin/master\" will show\n> what needs to be accepted by the upstream from you to reproduce your\n> work in full; if you run \"git format-patch master\", it may miss some\n> parts that you already have in your local 'master' but not yet in\n> the upstream.\n>\n> I never talked about conflicts, and I still think that it is\n> completely outside the scope of these examples. Avoidance of\n> conflicts with the work that is already commited to your upstream\n> since you forked is the job for \"rebase\", not \"format-patch\". The\n> reason why it is wrong to replace 'origin' in that text with 'master'\n> does not have anything to do with conflict avoidance.\n>\n> Puzzled...\n> --\nDid any of that help?\n--\nPhilip \n"},{"id":"247282","messageId":"xmqqlhr2pzoe.fsf@gitster.dls.corp.google.com","threadId":"37277","inReplyTo":"C4E435A5EF324ABCBCC0930A9EB56141@PhilipOakley","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-05T18:19:13Z","receivedAt":"2014-08-05T18:19:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n> ...\n>> Nowhere I am assuming that \"the reader is creating paches based on\n>> wherever someone else had got to\". Sorry, but I have no idea what\n>> you are complaining about.\n>\n> I think we are talking at cross purposes. My starting point is that\n> (the examples says that) the reader wants to create a patch series for\n> a local branch, relative to their branch which they\n> branched from...\n\nPerhaps what you are missing is that the 'origin' in that example is\nnot \"their\" branch. It is how we used to spell what we\ncall 'refs/remotes/origin/HEAD' these days, a copy of their upstream\nrepository's primary branch.\n\n> (e.g. the example, relative to Git, could have been from\n> branched from (e.g. the example, relative to Git, could have been from\n> a 'pu' picked up a couple of days earlier, when they'd have said 'git\n> format-patch pu' ;-).\n\nAgain, if that were a \"'pu' picked up a few days earlier, it would\nnot be 'pu', but be 'origin/pu'\".\n\n>> The primary reason why 'origin' in the example should be replaced\n>> with 'origin/master' is because that is the literal adjustment from\n>> the pre-separate-remote world order to today's world order.\n>\n> I was trying to avoid a literal adjustment to what I'd perceived as a\n> presumed workflow.\n\nThese are \"examples\", showing uses of commands in some hopefully\ncommon scenarios. I am not exactly sure what you are aiming at, but\nif you are trying to strip context and/or background from them and\ntrying to limit them purely to \"If you do X, Y happens\", the\nresulting description would lack clues that readers rely on in order\nto choose the usage pattern of the command that is suitable for\ntheir situation, which I do not think is a good change to make. The\nreaders would be helped more with \"You are in state A and want to\nachieve B. If you do X starting from state A, Y happens, which helps\nyou achieve B.\", and that is what examples are about.\n\nNow, these \"where you are and what you want to do\" may not be\nexplicitly spelled out to avoid redundancy, and it may be an\nimprovement to enhance the scenario without making them too narrow.\nBut that would be a separate change, and renaming 'origin' (whose\nmodern equivalent is 'origin/master' in the context of these\nexamples) to 'master' alone would not do any such enhancement.\n\n>> The\n>> local branch 'origin' (more specifically, 'refs/heads/origin') used\n>> to be what we used to keep track of 'master' of the upstream, which\n>> we use 'refs/remotes/origin/master' these days.\n>>\n>> Side note: DWIMming origin to remotes/origin/HEAD to\n>> remotes/origin/master was invented to keep supporting this\n>> \"'origin' keeps track of the default upstream\" convention\n>> when we transitioned from the old world order to\n>> separate-remote layout.\n>>\n>> And the reason why 'origin' should not be replaced with 'master' is\n>> because your 'master' may already have patches from the topic you\n>> are working on, i.e. in your current branch, that the upstream does\n>> not yet have.\n>\n> So this a 'develop on master' view, rather than a 'develop on feature\n> branches' approach? Which could explain the misunderstanding.\n\nThe new work on the feature branches may be merged in 'master'\nwithout ever intending to push 'master' out. The development is\nstill done on the topic branches that are merged to your local\n'master', perhaps for testing purposes and most likely to personally\nuse it before the upstream picks them up.\n\nI suspect your misunderstanding is primarily coming from that you\nmay have forgotten, or you may be too new to know, that 'origin' in\nthe example, 'refs/heads/origin', used to be how we tracked the\nprimary branch of the other side back in the era when these examples\nwere written, and refs/remotes/origin/master is used for the same\ntracking these days.\n"}]}