{"thread":{"id":"37273","subject":"[PATCH] doc: format-patch: don't use origin as a branch name","startedAt":"2014-08-01T19:20:26Z","lastAt":"2014-08-01T22:26:02Z","messageCount":4,"participants":["Philip Oakley","Jonathan Nieder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"247126","messageId":"1406920826-4680-1-git-send-email-philipoakley@iee.org","threadId":"37273","inReplyTo":null,"subject":"[PATCH] doc: format-patch: don't use origin as a branch name","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-01T19:20:26Z","receivedAt":"2014-08-01T19:20:26Z","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. This is now used to name the remote.\nUse the more modern 'master' as the branch name.\n\nSigned-off-by: Philip Oakley \n---\n\nI noticed this while cross-checking details for updating the guide\nDocumentation/(git)everyday.txt\n--\nPhilip\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":"247128","messageId":"20140801193614.GR12427@google.com","threadId":"37273","inReplyTo":"1406920826-4680-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: format-patch: don't use origin as a branch name","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2014-08-01T19:36:14Z","receivedAt":"2014-08-01T19:36:14Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Philip Oakley wrote:\n\n> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch used\n> 'origin' as the upstream branch name. This is now used to name the remote.\n> Use the more modern 'master' as the branch name.\n\nWould 'origin/master' make sense?\n\nThanks,\nJonathan\n"},{"id":"247133","messageId":"xmqq8un8ug5d.fsf@gitster.dls.corp.google.com","threadId":"37273","inReplyTo":"20140801193614.GR12427@google.com","subject":"Re: [PATCH] doc: format-patch: don't use origin as a branch name","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-08-01T20:08:30Z","receivedAt":"2014-08-01T20:08:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Philip Oakley wrote:\n>\n>> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch used\n>> 'origin' as the upstream branch name. This is now used to name the remote.\n>> Use the more modern 'master' as the branch name.\n>\n> Would 'origin/master' make sense?\n\nIt would make a lot more sense than 'master', I think.\n\nThe 'origin' will be DWIMmed to whatever the remote designated as\nits primary branch, i.e. refs/remotes/origin/HEAD, and the\nassumption the examples in question makes is that the user is\nfollowing along the simplest workflow to fork from it and upstream\nher changes. Between 'origin' and 'origin/master', there isn't much\ndifference because of it. In the same spirit of following the\nsimplest workflow, that primary branch is likely to be their\n'master', so 'origin/master' is OK but longer than 'origin' [*1*].\n\nOn the other hand, 'master' names the local 'master', which may be\nvery stale with respect to 'origin/master', or may have tons of\nunrelated things that are not in origin/master, some of which may\nhave come from the branch the user is running format-patch to grab\npatches to upstream. For this reason, changing 'origin' to 'master'\nis not an improvement at all, I would have to say.\n\nWe could further adjust the underlying assumption to more modern\n\"checkout -t -b\" era, and use \"format-patch @{u}\", but I suspect\nthat the readers of these examples are not yet ready for magic\nbefore the basics to spell out things more explicitly is covered.\n\n\n[Footnote]\n\n*1* Also using 'origin' will cover the case when the primary branch\nat the remote were not named 'master', so in that sense it is\nslightly better and more generally applicable.\n"},{"id":"247149","messageId":"F09DC14751724BEB809135DE720953E6@PhilipOakley","threadId":"37273","inReplyTo":"xmqq8un8ug5d.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: format-patch: don't use origin as a branch name","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-08-01T22:26:02Z","receivedAt":"2014-08-01T22:26:02Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Jonathan Nieder writes:\n>\n>> Philip Oakley wrote:\n>>\n>>> Historically (5 Nov 2005 v0.99.9-46-g28ffb89) the git-format-patch \n>>> used\n>>> 'origin' as the upstream branch name. This is now used to name the \n>>> remote.\n>>> Use the more modern 'master' as the branch name.\n>>\n>> Would 'origin/master' make sense?\n>\n> It would make a lot more sense than 'master', I think.\n>\n> The 'origin' will be DWIMmed to whatever the remote designated as\n\nI'd rather not provide an example that requires extra understanding on \nbehalf of the reader on the DWIMing, especially as the example doesn't \nactually match the guidance in gitrevisions(7) [2].\n\nThe synopsis says it should either be a single commit , or a \n, the latter specified via gitrevisions(7), so theirs \nalready an opportunity for confusion, but I take your point.\n\n> its primary branch, i.e. refs/remotes/origin/HEAD, and the\n> assumption the examples in question makes is that the user is\n> following along the simplest workflow to fork from it and upstream\n> her changes. Between 'origin' and 'origin/master', there isn't much\n> difference because of it. In the same spirit of following the\n> simplest workflow, that primary branch is likely to be their\n> 'master', so 'origin/master' is OK but longer than 'origin' [*1*].\n\nwhich suggests that maybe the example text should clarify any assumprion \nlike that..\n>\n> On the other hand, 'master' names the local 'master', which may be\n> very stale with respect to 'origin/master', or may have tons of\n> unrelated things that are not in origin/master, some of which may\n> have come from the branch the user is running format-patch to grab\n> patches to upstream. For this reason, changing 'origin' to 'master'\n> is not an improvement at all, I would have to say.\n\nI didn't see it that way, my view (presumption?) of the workflow was \nthat the user had a branch 'current' which they had branched from their \n'master', thus the updated command felt natural.\n>\n> We could further adjust the underlying assumption to more modern\n> \"checkout -t -b\" era, and use \"format-patch @{u}\", but I suspect\n> that the readers of these examples are not yet ready for magic\n> before the basics to spell out things more explicitly is covered.\n\nagreed\n\n>\n>\n> [Footnote]\n>\n> *1* Also using 'origin' will cover the case when the primary branch\n> at the remote were not named 'master', so in that sense it is\n> slightly better and more generally applicable.\n>\n--\nPhilip\n[2] the DWIMs listed in the example of gitrevisions(7), to the \nniave reader, needs to be ref/ prefixed, which isn't what we'd hope \n(assuming they ever read it ;-). \n"}]}