{"thread":{"id":"37349","subject":"Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a branch name","startedAt":"2014-08-14T19:50:18Z","lastAt":"2014-08-14T19:50:18Z","messageCount":1,"participants":["Philip Oakley"],"isPatch":true,"patchVersion":2,"patchTotal":1},"messages":[{"id":"247726","messageId":"69D7BD4F1C8A46C2AEBD261FE8317EAC@PhilipOakley","threadId":"37349","inReplyTo":null,"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-14T19:50:18Z","receivedAt":"2014-08-14T19:50:18Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"resending - send mail failure\n----- Original Message ----- \nFrom: \"Philip Oakley\" \nTo: \"Junio C Hamano\" \nCc: \"GitList\" ; \"Jonathan Nieder\" \n\nSent: Wednesday, August 13, 2014 5:03 PM\nSubject: Re: [PATCH v2 1/1] doc: format-patch: don't use origin as a \nbranch name\n\n\n> From: \"Junio C Hamano\" \n> Sent: Tuesday, August 05, 2014 7:19 PM\n>> \"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\n>>> for\n>>> a local branch, relative to their branch which they\n>>> branched from...\n>>\n>> Perhaps what you are missing is that the 'origin' in that example is\n>> not \"their\" branch. It is how we used to spell what we\n>> call 'refs/remotes/origin/HEAD' these days, a copy of their upstream\n>> repository's primary branch.\n>\n> Aha, I had a revelation as to where you were coming from in terms of \n> workflow and now see what you were meaning, and how it differed from \n> my perception of the workflow.\n>\n> I've documented the different expectations at the end (for those \n> interested),\n> however of more interest is how the confusion happened and what can be\n> learned from it. We should be ensuring that the examples avoid any \n> such\n> confusion. It can't be assumed that readers appreciate the history of \n> Git so the starting example should be both simple relative to the \n> synopsis and give the any necessary background workflow info.\n>\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\n>>> from\n>>> a 'pu' picked up a couple of days earlier, when they'd have said \n>>> 'git\n>>> format-patch pu' ;-).\n>>\n>> Again, if that were a \"'pu' picked up a few days earlier, it would\n>> not be 'pu', but be 'origin/pu'\".\n>\n> We haven't been clear how the branch is 'picked up' which, to me, is\n> partly where the expectation diverged.\n>\n> The other aspect (to me, a more recent learner of git) is that\n> established users were already used to the integrated nature of the\n> remote's DAG, while it's a mental extra step for newer users to link\n> across the 'refs/remotes//' divide, when a lot of advice\n> is of the type 'don't work on/with remote branches - there be \n> dragons'.\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>>>\n>>> I was trying to avoid a literal adjustment to what I'd perceived as \n>>> a\n>>> presumed workflow.\n>>\n>> These are \"examples\", showing uses of commands in some hopefully\n>> common scenarios. I am not exactly sure what you are aiming at, but\n>> if you are trying to strip context and/or background from them and\n>> trying to limit them purely to \"If you do X, Y happens\", the\n>> resulting description would lack clues that readers rely on in order\n>> to choose the usage pattern of the command that is suitable for\n>> their situation, which I do not think is a good change to make. The\n>> readers would be helped more with \"You are in state A and want to\n>> achieve B. If you do X starting from state A, Y happens, which helps\n>> you achieve B.\", and that is what examples are about.\n>\n> At the moment the example already lacked sufficient context.\n>>\n>> Now, these \"where you are and what you want to do\" may not be\n>> explicitly spelled out to avoid redundancy, and it may be an\n>> improvement to enhance the scenario without making them too narrow.\n>> But that would be a separate change, and renaming 'origin' (whose\n>> modern equivalent is 'origin/master' in the context of these\n>> examples) 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 \n>>> feature\n>>> branches' approach? Which could explain the misunderstanding.\n>>\n>> The new work on the feature branches may be merged in 'master'\n>> without ever intending to push 'master' out. The development is\n>> still done on the topic branches that are merged to your local\n>> 'master', perhaps for testing purposes and most likely to personally\n>> use it before the upstream picks them up.\n>>\n>> I suspect your misunderstanding is primarily coming from that you\n>> may have forgotten, or you may be too new to know, that 'origin' in\n>> the example, 'refs/heads/origin', used to be how we tracked the\n>> primary branch of the other side back in the era when these examples\n>> were written, and refs/remotes/origin/master is used for the same\n>> tracking these days.\n>> --\n>\n> I'll look to update the patch for review in the next week or so, \n> though family/work commitments may delay further.\n>\n> Philip\n>\n> Ascii art of the workflows\n> Example: Documented\n> ===================\n>\n> Build on top workflow; With fetch, not pull, update\n>\n> The user is working on top of his 'master' branch.\n>\n> / - origin/master\n> ¦\n> A - B - C - x - y - z (local) master [built upon origin/master]\n> \\\n> \\\n> D - E - G\n> ^ (refreshed/fetched from upstream) \n> origin/master\n>\n> In both cases (with or without a refresh/fetch from upstream), 'git\n> format-patch origin/master' will find commit 'C' as the branch point\n> (aka merge-base), and will create patches for commits x, y, and z.\n>\n> This is the workflow I think Junio is using as his basis for \n> discussion.\n> (This fits well with the historic methods of working with remotes, \n> which\n> were not as explicit differentiated as they are now)\n>\n> With this simple [easy] view of that worflow then:\n> At some point, when the patchs have been accepted upstream, one must\n> drop one's current (local) master branch and 'git reset --hard\n> origin/master' to become up to date with the upstream.\n>\n> --\n>\n> My viewpoint, based on my development on 'pu' style coding would start\n> with this view of the described flow. (Here the starting point is that\n> remotes are viewed as 'separate' from local branches.)\n>\n> / - origin/master when development started,\n> ¦ ref no longer valid.\n> ¦\n> A - B - C - x - y - z (local) master [built upon origin/master]\n> \\\n> \\\n> B'- C'- D - E - G (fetched) upstream has rewound/rebased\n> ¦ (as per some published policy)\n> ¦\n> ^ (refreshed) origin/master\n>\n> Note that here the 'git format-patch origin/master' will find commit \n> 'A'\n> as the branch point (aka merge-base), and produce additional patches \n> for\n> commits B and C as well as the desired x, y & z. Hence my initial \n> replies.\n>\n>\n> In fact my workflow doesn't develop 'on-top', rather uses the 'feature\n> branch' viewpoint, so:\n>\n>\n> / - origin/master when development started,\n> ¦ ref no longer valid.\n> ¦\n> A - B - C (local) master\n> ¦ ¦ [starts at original origin/master]\n> ¦ \\\n> ¦ \\ x - y - z (feature branch) 'current'\n> \\\n> \\\n> B'- C'- D - E - G upstream has rewound/rebased\n> ¦ (e.g. as per published policy *note*)\n> ¦\n> ^ (refreshed) origin/master\n>\n> Here the command 'git format-patch origin/master' would be wrong (as\n> above), while 'git format-patch master' would be the desired user \n> action\n> (patches just for x, y & z).\n>\n> *note*: while rewinding 'master' is untypical (if not insane), it can \n> be normal for some published branches, e.g. Git's pu branch. \n"}]}