{"thread":{"id":"40318","subject":"storing cover letter of a patch series?","startedAt":"2015-09-10T16:28:52Z","lastAt":"2016-08-16T21:29:40Z","messageCount":57,"participants":["Jacob Keller","Junio C Hamano","Martin Fick","Johannes Schindelin","Philip Oakley","Chris Packham","Simon Glass","Michael S. Tsirkin","John Keeping","Duy Nguyen","Stefan Beller","Michael J Gruber"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"269702","messageId":"CA+P7+xpHDGY5RTR8ntrABdxqM6b4V9dndS68=kV1+1Ym1N6YKw@mail.gmail.com","threadId":"40318","inReplyTo":null,"subject":"storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T16:28:52Z","receivedAt":"2015-09-10T16:28:52Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"Hey,\n\ndoes anyone know of any tricks for storing a cover letter for a patch\nseries inside of git somehow? I'd guess the only obvious way currently\nis to store it at the top of the series as an empty commit.. but this\ndoesn't get emailed *as* the cover letter...\n\nIs there some other way? Would others be interested in such a feature?\n\nI get very annoyed when I've written a nice long patch cover letter in\nvim before an email and then realize I should fix something else up,\nor accidentally cancel it because I didn't use the write \"To:\" address\nor something..\n\nI really think it should be possible to store something somehow as a\nblob that could be looked up later. Even if this was a slightly more\nmanual process that would be helpful to store the message inside git\nitself.\n\nIn addition, this would help re-rolls since it would mean if I go back\nto a topic and re-roll it I can just update the message. If it were\nproperly stored in my local history that would also mean I could see\nrevisions on it.\n\nAny thoughts on how to do this?\n\nRegards,\nJake\n"},{"id":"269716","messageId":"xmqqh9n241el.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CA+P7+xpHDGY5RTR8ntrABdxqM6b4V9dndS68=kV1+1Ym1N6YKw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-09-10T17:41:54Z","receivedAt":"2015-09-10T17:41:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jacob Keller writes:\n\n> Is there some other way? Would others be interested in such a feature?\n\nNot me.\n\n> I get very annoyed when I've written a nice long patch cover letter in\n> vim before an email and then realize I should fix something else up,\n> or accidentally cancel it because I didn't use the write \"To:\" address\n> or something..\n\nI smell a fallout of encouraging a suboptimal workflow made by\ngit-send-email here. If you did not know that the command can drive\nformat-patch itself, your workflow would have been:\n\n $ git format-patch -o my-topic --cover master..my-topic\n $ vi my-topic/*.txt\n\nand only after you gain confidence with the edited result\n\n $ git send-email $args my-topic/*.txt\n\nwhich has no room for your grief/complaint to come into the\npicture. While rerolling, you can do the same\n\n $ git format-patch -o my-topic --cover -v2 master..my-topic\n\nand reuse major parts of cover letter from the original round.\n\n> I really think it should be possible to store something somehow as a\n> blob that could be looked up later.\n\nI think \"should\" is too strong here. Yes, you could implement that\nway. It is debatable if it is better, or a flat file kept in a\ndirectory (my-topic/ in the example above) across rerolls is more\nflexible, lightweight and with less mental burden to the users.\n"},{"id":"269720","messageId":"18979417.pyyHNUINeQ@mfick1-lnx","threadId":"40318","inReplyTo":"xmqqh9n241el.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Martin Fick","fromEmail":"mfick@codeaurora.org","sentAt":"2015-09-10T18:02:02Z","receivedAt":"2015-09-10T18:02:02Z","isPatch":false,"sender":{"key":"mfick@codeaurora.org","avatar":null},"body":"+repo-discuss@googlegroups.com (to hit Gerrit developers \nalso)\n\nOn Thursday, September 10, 2015 09:28:52 AM Jacob Keller \n wrote:\n> does anyone know of any tricks for storing a cover letter\n> for a patch series inside of git somehow? I'd guess the\n> only obvious way currently is to store it at the top of\n> the series as an empty commit.. but this doesn't get\n> emailed as the cover letter...\n...\n> I really think it should be possible to store something\n> somehow as a blob that could be looked up later.\n\n\nOn Thursday, September 10, 2015 10:41:54 AM Junio C Hamano \nwrote:\n> \n> I think \"should\" is too strong here. Yes, you could\n> implement that way. It is debatable if it is better, or\n> a flat file kept in a directory (my-topic/ in the example\n> above) across rerolls is more flexible, lightweight and\n> with less mental burden to the users. --\n\nAs a Gerrit developer and user, I would like a way to \nsee/review cover letters in Gerrit. We have had many \ninternal proposals, most based on git notes, but we have \nalso used the empty commit trick. It would be nice if there \nwere some standard git way to do this so that Gerrit and \nother tools could benefit from this standard. I am not \nsuggesting that git need to be modified to do this, but \nrather that at least some convention be established.\n\n-Martin\n\n\n-- \nThe Qualcomm Innovation Center, Inc. is a member of Code \nAurora Forum, hosted by The Linux Foundation\n\n-- \n"},{"id":"269724","messageId":"CA+P7+xq9P2NHqQe-y+2n38ZvbR74UxR0Rik=btgy=JtEoZbX2A@mail.gmail.com","threadId":"40318","inReplyTo":"xmqqh9n241el.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T18:32:35Z","receivedAt":"2015-09-10T18:32:35Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Thu, Sep 10, 2015 at 10:41 AM, Junio C Hamano wrote:\n> Jacob Keller writes:\n>\n>> Is there some other way? Would others be interested in such a feature?\n>\n> Not me.\n>\n>> I get very annoyed when I've written a nice long patch cover letter in\n>> vim before an email and then realize I should fix something else up,\n>> or accidentally cancel it because I didn't use the write \"To:\" address\n>> or something..\n>\n> I smell a fallout of encouraging a suboptimal workflow made by\n> git-send-email here. If you did not know that the command can drive\n> format-patch itself, your workflow would have been:\n>\n> $ git format-patch -o my-topic --cover master..my-topic\n> $ vi my-topic/*.txt\n>\n> and only after you gain confidence with the edited result\n>\n> $ git send-email $args my-topic/*.txt\n>\n\nI hadn't thought of separating the cover letter from git-send-email.\nThat would be suitable for me.\n\n> which has no room for your grief/complaint to come into the\n> picture. While rerolling, you can do the same\n>\n> $ git format-patch -o my-topic --cover -v2 master..my-topic\n>\n> and reuse major parts of cover letter from the original round.\n>\n>> I really think it should be possible to store something somehow as a\n>> blob that could be looked up later.\n>\n> I think \"should\" is too strong here. Yes, you could implement that\n> way. It is debatable if it is better, or a flat file kept in a\n> directory (my-topic/ in the example above) across rerolls is more\n> flexible, lightweight and with less mental burden to the users.\n\nThis seems reasonable from an email point of view. Thanks for the insight.\n\nRegards,\nJake\n"},{"id":"269725","messageId":"CA+P7+xp9bMeQF2TvNoGTcL4H5Ap0vHcDhJ0o4WCpaAJaFmQmeA@mail.gmail.com","threadId":"40318","inReplyTo":"18979417.pyyHNUINeQ@mfick1-lnx","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T18:38:42Z","receivedAt":"2015-09-10T18:38:42Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Thu, Sep 10, 2015 at 11:02 AM, Martin Fick wrote:\n> On Thursday, September 10, 2015 10:41:54 AM Junio C Hamano\n> wrote:\n>>\n>> I think \"should\" is too strong here. Yes, you could\n>> implement that way. It is debatable if it is better, or\n>> a flat file kept in a directory (my-topic/ in the example\n>> above) across rerolls is more flexible, lightweight and\n>> with less mental burden to the users. --\n>\n> As a Gerrit developer and user, I would like a way to\n> see/review cover letters in Gerrit. We have had many\n> internal proposals, most based on git notes, but we have\n> also used the empty commit trick. It would be nice if there\n> were some standard git way to do this so that Gerrit and\n> other tools could benefit from this standard. I am not\n> suggesting that git need to be modified to do this, but\n> rather that at least some convention be established.\n>\n> -Martin\n>\n\nHaving used gerrit, this would be useful as well. The \"empty commit\nmessage\" thing sort of works, but has issues.\n\nI don't know if this could be solved for gerrit at all without\nmodification to git, since you'd need something that can be sent to\nthe gerrit server and received by the client.\n\nSome form of git-notes might work, ie: a git-notes on the first\ncommit, stored in some \"standard\" refs/notes/cover or similar.. but\nthis would depend on implementation of a standard way to share notes.\n\nOne alternative as well is to use a --no-ff merge commit which forces\nthe merge between the base and the tip of the series and contains the\ncontents.. but I don't believe gerrit really works well with merge\ncommits.\n\nBut again, Junio's solution will work great for emails workflow, which\nis my primary usage.\n"},{"id":"269726","messageId":"xmqqzj0u2k5m.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"18979417.pyyHNUINeQ@mfick1-lnx","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-09-10T18:39:49Z","receivedAt":"2015-09-10T18:39:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Fick writes:\n\n> As a Gerrit developer and user, I would like a way to \n> see/review cover letters in Gerrit. We have had many \n> internal proposals, most based on git notes, but we have \n> also used the empty commit trick. It would be nice if there \n> were some standard git way to do this so that Gerrit and \n> other tools could benefit from this standard. I am not \n> suggesting that git need to be modified to do this, but \n> rather that at least some convention be established.\n\nSome of what you would write in the cover letter is not meant for\nanywhere in the permanent history (e.g. description of what changed\nsince the previous reroll), but some other would be a concise\nsummary of what the entire series is about, and it would be nice if\nit can be made part of the permanent record.\n\nThe problem with \"empty commit trick\" is that it is a commit whose\nsole purpose is to describe the series, and its presence makes it\nclear where the series ends, but the topology does not tell where\nthe series begins, so it is an unsatisifactory half-measure.\n\nIdeally, I would think that you want that information when the\nseries is fully cooked and gets merged to a more permanent place in\nthe log message of the merge commit. At that point, where the\nseries started may become more clear from the topology (i.e. the set\ndifference X^..X for the resulting merge is what got merged). One\npossible \"hacky\" convention could be\n\n - Developers keep rerolling with the \"empty commit with cover\n letter material at the tip\". topic@{upstream}..topic~1 are the\n real changes, topic~0 is an empty \"cover letter material\".\n\n - When the series is fully cooked, a new \"git merge\" option notices\n that the topic is structured in a \"strange\" way, uncaps its tip\n commit and merges the remainder of the series and adds the cover\n letter material when presenting the editor to record the merge\n commit. That is\n\n\t$ git merge --cover-at-tip topic\n\n would work roughly by doing the following:\n\n - verify that \"git rev-parse topic^^{tree} topic^{tree}\" shows that\n they record the same tree; otherwise it will error out, saying\n the tip is not a pure cover.\n\n - verify that \"git rev-list ..topic^\" shows that there is\n something to merge after the tip is removed; otherwise it will\n error out, saying that there is nothing to merge.\n\n - run \"git merge --no-ff --edit topic^1\" but with the log\n message of topic^{commit} in the editor's template.\n"},{"id":"269727","messageId":"xmqqvbbi2jy5.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CA+P7+xq9P2NHqQe-y+2n38ZvbR74UxR0Rik=btgy=JtEoZbX2A@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-09-10T18:44:18Z","receivedAt":"2015-09-10T18:44:18Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jacob Keller writes:\n\n> I hadn't thought of separating the cover letter from git-send-email.\n> That would be suitable for me.\n\nYeah, I said this number of times over time, and I said it once\nrecently in another thread, but I think it was a mistake to allow\ngit-send-email to drive format-patch. It may appear that it will\nmake things convenient in the perfect world where no user makes\nmistakes, but people are not perfect in real life. Expecting them\nto be is being naive.\n"},{"id":"269728","messageId":"CA+P7+xodgeu6Vo+Rt57_iFycxkEnNjxP-TTOfY8DdXwzeVKbZg@mail.gmail.com","threadId":"40318","inReplyTo":"xmqqvbbi2jy5.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T18:46:21Z","receivedAt":"2015-09-10T18:46:21Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Thu, Sep 10, 2015 at 11:44 AM, Junio C Hamano wrote:\n> Jacob Keller writes:\n>\n>> I hadn't thought of separating the cover letter from git-send-email.\n>> That would be suitable for me.\n>\n> Yeah, I said this number of times over time, and I said it once\n> recently in another thread, but I think it was a mistake to allow\n> git-send-email to drive format-patch. It may appear that it will\n> make things convenient in the perfect world where no user makes\n> mistakes, but people are not perfect in real life. Expecting them\n> to be is being naive.\n>\n\nYep. I didn't even know cover-letter was an option of format-patch\nonly thought it was in send-email.\n\nRegards,\nJake\n"},{"id":"269730","messageId":"74514591d4cd502eee06cde3e099e656@dscho.org","threadId":"40318","inReplyTo":"CA+P7+xpHDGY5RTR8ntrABdxqM6b4V9dndS68=kV1+1Ym1N6YKw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2015-09-10T18:58:49Z","receivedAt":"2015-09-10T18:58:49Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Jake,\n\nOn 2015-09-10 18:28, Jacob Keller wrote:\n\n> does anyone know of any tricks for storing a cover letter for a patch\n> series inside of git somehow?\n\nIt is not stored as a blob, but I use `git branch --edit-description` to write the cover letter for patch series when I expect a couple of iterations.\n\nCiao,\nDscho\n"},{"id":"269734","messageId":"A20C476954134C53B0D256D644B1CCC2@PhilipOakley","threadId":"40318","inReplyTo":"CA+P7+xodgeu6Vo+Rt57_iFycxkEnNjxP-TTOfY8DdXwzeVKbZg@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-10T20:09:25Z","receivedAt":"2015-09-10T20:09:25Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jacob Keller\" \n> On Thu, Sep 10, 2015 at 11:44 AM, Junio C Hamano \n> wrote:\n>> Jacob Keller writes:\n>>\n>>> I hadn't thought of separating the cover letter from git-send-email.\n>>> That would be suitable for me.\n>>\n>> Yeah, I said this number of times over time, and I said it once\n>> recently in another thread, but I think it was a mistake to allow\n>> git-send-email to drive format-patch. It may appear that it will\n>> make things convenient in the perfect world where no user makes\n>> mistakes, but people are not perfect in real life. Expecting them\n>> to be is being naive.\n>>\n>\n> Yep. I didn't even know cover-letter was an option of format-patch\n> only thought it was in send-email.\n>\nActually, the one feature I'd like (I think) is to be able to join \ntogether the empty commit mechanism and the cover letter mechanism \nwithin format patch so that:\n\n* the empty commit message would detected and automatically become the \n[0/N] in the patch series (without need to say --cover-letter)\n\n* the cover letter would still have some 'template' markings to say \"*** \ninsert what's changed here***\" or smilar (with option to exclude them).\n\nThat way, when starting a series / branch, the first item would be to \nadd the explanatory 'empty commit' that states the requirements of what \none hopes to achieve (a key cover letter content), which is then \nfollowed by commits that move toward that goal.\n\nThe series can then be rebased as the user develops the code, and that \ncover note can be edited as required during the rebase.\n\nWhen it comes time to show it to the list, the format patch will *know* \nfrom the empty commit that it is the [0/N] cover letter and \n(perhaps -option) add the appropriate markers ready for editing.\n\nThe user edits the cover letter with the extra 'what's changed' / \ninterdiff / whatever, and sends. sendmail barfs if the user hasn't \nedited the markers.\n\nThis could also work with the sendmail patch formating (though I've \nnever used that workflow) as now the cover letter becomes automatic for \nthe upstream.\n\nPhilip \n"},{"id":"269738","messageId":"CA+P7+xrH6v7AVaH_su2X3xx7qs_uws-r-DozzYELm_O8g+oN9A@mail.gmail.com","threadId":"40318","inReplyTo":"74514591d4cd502eee06cde3e099e656@dscho.org","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T21:00:02Z","receivedAt":"2015-09-10T21:00:02Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Thu, Sep 10, 2015 at 11:58 AM, Johannes Schindelin\n wrote:\n> Hi Jake,\n>\n> On 2015-09-10 18:28, Jacob Keller wrote:\n>\n>> does anyone know of any tricks for storing a cover letter for a patch\n>> series inside of git somehow?\n>\n> It is not stored as a blob, but I use `git branch --edit-description` to write the cover letter for patch series when I expect a couple of iterations.\n>\n> Ciao,\n> Dscho\n\nDoes this (or can it?) get used by send-email or format-patch's\n--cover-letter? This sounds like exactly what I want.\n\nRegards,\nJake\n"},{"id":"269739","messageId":"CA+P7+xq2H-ZRix_71bQdswuEm++64ZA8FmK7J+1jhUhFeCZbgg@mail.gmail.com","threadId":"40318","inReplyTo":"A20C476954134C53B0D256D644B1CCC2@PhilipOakley","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-10T21:03:48Z","receivedAt":"2015-09-10T21:03:48Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Thu, Sep 10, 2015 at 1:09 PM, Philip Oakley wrote:\n> From: \"Jacob Keller\" \n>>\n>> On Thu, Sep 10, 2015 at 11:44 AM, Junio C Hamano \n>> wrote:\n>>>\n>>> Jacob Keller writes:\n>>>\n>>>> I hadn't thought of separating the cover letter from git-send-email.\n>>>> That would be suitable for me.\n>>>\n>>>\n>>> Yeah, I said this number of times over time, and I said it once\n>>> recently in another thread, but I think it was a mistake to allow\n>>> git-send-email to drive format-patch. It may appear that it will\n>>> make things convenient in the perfect world where no user makes\n>>> mistakes, but people are not perfect in real life. Expecting them\n>>> to be is being naive.\n>>>\n>>\n>> Yep. I didn't even know cover-letter was an option of format-patch\n>> only thought it was in send-email.\n>>\n> Actually, the one feature I'd like (I think) is to be able to join together\n> the empty commit mechanism and the cover letter mechanism within format\n> patch so that:\n>\n> * the empty commit message would detected and automatically become the [0/N]\n> in the patch series (without need to say --cover-letter)\n>\n> * the cover letter would still have some 'template' markings to say \"***\n> insert what's changed here***\" or smilar (with option to exclude them).\n>\n> That way, when starting a series / branch, the first item would be to add\n> the explanatory 'empty commit' that states the requirements of what one\n> hopes to achieve (a key cover letter content), which is then followed by\n> commits that move toward that goal.\n>\n> The series can then be rebased as the user develops the code, and that cover\n> note can be edited as required during the rebase.\n>\n> When it comes time to show it to the list, the format patch will *know* from\n> the empty commit that it is the [0/N] cover letter and (perhaps -option) add\n> the appropriate markers ready for editing.\n>\n> The user edits the cover letter with the extra 'what's changed' / interdiff\n> / whatever, and sends. sendmail barfs if the user hasn't edited the markers.\n>\n> This could also work with the sendmail patch formating (though I've never\n> used that workflow) as now the cover letter becomes automatic for the\n> upstream.\n>\n> Philip\n\nIf there was a way to store this empty commit message tagged as \"cover\nletter\" that could work well, though generally I prefer the\nnon-fast-forward merges as this shows you where the series ended *and*\nbegan. It's somewhat confusing to newer users.. and this doesn't get\nrebased very well either.\n\nSome way to indicate a particular \"empty\" commit is actually a cover\nletter seems easy enough. This seems like the way that I was thinking.\n\nUsing \"edit description\" of git-branch seems also to be pretty\neffective for this, even if it doesn't get shared across remotes. (not\nreally a necessary feature for what I do).\n\nBut having some way to indicate \"cover letter\" which gets used as the\nbeginning of a log message when doing a particular \"merge\n--tip-as-cover\" or something like Junio suggested above seems like the\nnicest approach.\n\nRegards,\nJake\n"},{"id":"269742","messageId":"5f1102c0fcdb3530148ae7a6a18bd0a7@dscho.org","threadId":"40318","inReplyTo":"CA+P7+xrH6v7AVaH_su2X3xx7qs_uws-r-DozzYELm_O8g+oN9A@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2015-09-10T21:21:19Z","receivedAt":"2015-09-10T21:21:19Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Jake,\n\nOn 2015-09-10 23:00, Jacob Keller wrote:\n> On Thu, Sep 10, 2015 at 11:58 AM, Johannes Schindelin\n> wrote:\n>>\n>> On 2015-09-10 18:28, Jacob Keller wrote:\n>>\n>>> does anyone know of any tricks for storing a cover letter for a patch\n>>> series inside of git somehow?\n>>\n>> It is not stored as a blob, but I use `git branch --edit-description` to write the cover letter for patch series when I expect a couple of iterations.\n> \n> Does this (or can it?) get used by send-email or format-patch's\n> --cover-letter? This sounds like exactly what I want.\n\nYes, format-patch picks it up if you say `--cover-letter`.\n\nCiao,\nJohannes\n\nP.S.: Please do cut down the quoted text to the part you are actually responding to. Bottom-posting is not much better than top-posting...\n"},{"id":"269746","messageId":"A29E37E55E524B9FACB67EC05486A178@PhilipOakley","threadId":"40318","inReplyTo":"5f1102c0fcdb3530148ae7a6a18bd0a7@dscho.org","subject":"Re: storing cover letter of a patch series?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-10T22:20:55Z","receivedAt":"2015-09-10T22:20:55Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Johannes Schindelin\" \n> On 2015-09-10 23:00, Jacob Keller wrote:\n>> On Thu, Sep 10, 2015 at 11:58 AM, Johannes Schindelin\n>> wrote:\n>>>\n>>> On 2015-09-10 18:28, Jacob Keller wrote:\n>>>\n>>>> does anyone know of any tricks for storing a cover letter for a \n>>>> patch\n>>>> series inside of git somehow?\n>>>\n>>> It is not stored as a blob, but I use `git \n>>> branch --edit-description` to write the cover letter for patch \n>>> series when I expect a couple of iterations.\n>>\n>> Does this (or can it?) get used by send-email or format-patch's\n>> --cover-letter? This sounds like exactly what I want.\n>\n> Yes, format-patch picks it up if you say `--cover-letter`.\n>\n\nI didn't know that. It doesn't appear to be mentioned in the man pages.\n\nIIUC https://github.com/git/git/blob/master/builtin/log.c#L971 suggests \nthat it is a deliberate extra inclusion, rather than being part of the \nshortlog and diffstat mentioned in the manual \nhttps://github.com/git/git/blob/master/Documentation/git-format-patch.txt#L216\n\nSounds like it may be a worthwhile doc patch.\n--\nPhilip \n"},{"id":"269755","messageId":"CAFOYHZB3dKgi3rERHXuWynTjYQu+iPVdbWqmtoD+irYopfoRCg@mail.gmail.com","threadId":"40318","inReplyTo":"CA+P7+xpHDGY5RTR8ntrABdxqM6b4V9dndS68=kV1+1Ym1N6YKw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Chris Packham","fromEmail":"judge.packham@gmail.com","sentAt":"2015-09-11T08:30:04Z","receivedAt":"2015-09-11T08:30:04Z","isPatch":false,"sender":{"key":"judge.packham@gmail.com","avatar":"https://avatars.githubusercontent.com/u/155667?v=4"},"body":"On Fri, Sep 11, 2015 at 4:28 AM, Jacob Keller wrote:\n> Hey,\n>\n> does anyone know of any tricks for storing a cover letter for a patch\n> series inside of git somehow? I'd guess the only obvious way currently\n> is to store it at the top of the series as an empty commit.. but this\n> doesn't get emailed *as* the cover letter...\n>\n> Is there some other way? Would others be interested in such a feature?\n>\n> I get very annoyed when I've written a nice long patch cover letter in\n> vim before an email and then realize I should fix something else up,\n> or accidentally cancel it because I didn't use the write \"To:\" address\n> or something..\n>\n> I really think it should be possible to store something somehow as a\n> blob that could be looked up later. Even if this was a slightly more\n> manual process that would be helpful to store the message inside git\n> itself.\n>\n> In addition, this would help re-rolls since it would mean if I go back\n> to a topic and re-roll it I can just update the message. If it were\n> properly stored in my local history that would also mean I could see\n> revisions on it.\n>\n> Any thoughts on how to do this?\n>\n\nA bit of a plug for patman[1] which the u-boot project uses (although\nthere's nothing u-boot specific about it). It lets you put the cover\nletter and other meta information in the commit messages as you go\nthen will extract that information and generate a cover letter and\nclean patches. As of fairly recently it's also installable as a\nstandalone application.\n\n--\n[1] - http://git.denx.de/?p=u-boot.git;a=blob;f=tools/patman/README\n"},{"id":"269802","messageId":"xmqq37ykzjaj.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"xmqqzj0u2k5m.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-09-11T22:24:20Z","receivedAt":"2015-09-11T22:24:20Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ideally, I would think that you want that information when the\n> series is fully cooked and gets merged to a more permanent place in\n> the log message of the merge commit. At that point, where the\n> series started may become more clear from the topology (i.e. the set\n> difference X^..X for the resulting merge is what got merged). One\n> possible \"hacky\" convention could be\n>\n> - Developers keep rerolling with the \"empty commit with cover\n> letter material at the tip\". topic@{upstream}..topic~1 are the\n> real changes, topic~0 is an empty \"cover letter material\".\n>\n> - When the series is fully cooked, a new \"git merge\" option notices\n> that the topic is structured in a \"strange\" way, uncaps its tip\n> commit and merges the remainder of the series and adds the cover\n> letter material when presenting the editor to record the merge\n> commit. That is\n>\n> \t$ git merge --cover-at-tip topic\n>\n> would work roughly by doing the following:\n>\n> - verify that \"git rev-parse topic^^{tree} topic^{tree}\" shows that\n> they record the same tree; otherwise it will error out, saying\n> the tip is not a pure cover.\n>\n> - verify that \"git rev-list ..topic^\" shows that there is\n> something to merge after the tip is removed; otherwise it will\n> error out, saying that there is nothing to merge.\n>\n> - run \"git merge --no-ff --edit topic^1\" but with the log\n> message of topic^{commit} in the editor's template.\n\nTo complement the above, if we want to pursue this approach, the\nfollowing would also help.\n\n - (obvious) \"git pull\" would learn the same \"--cover-at-tip\" option\n and would pass it to \"git merge\".\n\n - \"git am --cover-at-tip\" would make the incoming cover-letter\n material into a non-tree-changing commit at the tip of the\n resulting topic.\n\n - \"git format-patch\" would notice a topic branch in such a shape\n and would use the log message of the non-tree-changing commit at\n the tip as part of the cover letter.\n\nThen the overall workflow would become:\n\n * A developer works on a topic and concludes it by writing a\n summary that should appear in the final merge to the trunk as a\n log message of a non-tree-changing commit at the tip.\n\n * In \"request-to-pull\" workflow, the developer requests the topic\n to be pulled. The integrator uses \"git pull --cover-at-tip\" and\n the resulting merge commit will carry the summary written by the\n original developer.\n\n * In e-mail workflow, the developer runs \"git format-patch\"; the\n cover-letter is populated with the summary the developer wrote.\n\n * The integrator uses \"git am --cover-at-tip\" on a new branch,\n which recreates the topic branch the developer created at the\n first step above.\n\n * The integrator merges the topic with \"git merge --cover-at-tip\"\n to the trunk, and the resulting merge commit will carry the\n summary written by the original developer.\n"},{"id":"269838","messageId":"1442098288-3316-1-git-send-email-philipoakley@iee.org","threadId":"40318","inReplyTo":"74514591d4cd502eee06cde3e099e656@dscho.org","subject":"[PATCH] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-12T22:51:28Z","receivedAt":"2015-09-12T22:51:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The branch description will be included in 'git format-patch\n--cover-letter' and in 'git pull-request' emails. Tell the reader.\n\nWhile here, clarify that the description may be a multi-line\nexplanation of the purpose of the branch's patch series.\n\nSigned-off-by: Philip Oakley \n---\n\nThis is a short doc patch to follow up $gmane/277628 where Johannes\nSchindelin noted this otherwise undocumented feature.\n\n\n Documentation/git-branch.txt | 3 ++-\n Documentation/git-format-patch.txt | 2 +-\n Documentation/git-request-pull.txt | 3 ++-\n 3 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex a67138a..79ad1c7 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -197,7 +197,8 @@ start-point is either a local or remote-tracking branch.\n \n --edit-description::\n \tOpen an editor and edit the text to explain what the branch is\n-\tfor, to be used by various other commands (e.g. `request-pull`).\n+\tfor, to be used by various other commands (e.g. `format-patch`\n+\tand `request-pull`). Multi-line explanations may be used.\n \n --contains []::\n \tOnly list branches which contain the specified commit (HEAD\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 0dac4e9..4035649 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -213,7 +213,7 @@ feeding the result to `git send-email`.\n \n --[no-]cover-letter::\n \tIn addition to the patches, generate a cover letter file\n-\tcontaining the shortlog and the overall diffstat. You can\n+\tcontaining the branch description, shortlog and the overall diffstat. You can\n \tfill in a description in the file before sending it out.\n \n --notes[=]::\ndiff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt\nindex 283577b..c32cb0b 100644\n--- a/Documentation/git-request-pull.txt\n+++ b/Documentation/git-request-pull.txt\n@@ -14,7 +14,8 @@ DESCRIPTION\n -----------\n \n Generate a request asking your upstream project to pull changes into\n-their tree. The request, printed to the standard output, summarizes\n+their tree. The request, printed to the standard output,\n+begins with the branch description, summarizes\n the changes and indicates from where they can be pulled.\n \n The upstream project is expected to have the commit named by\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"269841","messageId":"CA+P7+xqh0e+2aMZf8i-1hBc0fMgaz0UjVdboLv+L9+rBYBR85w@mail.gmail.com","threadId":"40318","inReplyTo":"1442098288-3316-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2015-09-12T23:44:46Z","receivedAt":"2015-09-12T23:44:46Z","isPatch":true,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"Hi,\n\nOn Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley wrote:\n> The branch description will be included in 'git format-patch\n> --cover-letter' and in 'git pull-request' emails. Tell the reader.\n>\n> While here, clarify that the description may be a multi-line\n> explanation of the purpose of the branch's patch series.\n>\n> Signed-off-by: Philip Oakley \n> ---\n>\n> This is a short doc patch to follow up $gmane/277628 where Johannes\n> Schindelin noted this otherwise undocumented feature.\n>\n\nThanks for this.\n\n>\n> Documentation/git-branch.txt | 3 ++-\n> Documentation/git-format-patch.txt | 2 +-\n> Documentation/git-request-pull.txt | 3 ++-\n> 3 files changed, 5 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index a67138a..79ad1c7 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -197,7 +197,8 @@ start-point is either a local or remote-tracking branch.\n>\n> --edit-description::\n> Open an editor and edit the text to explain what the branch is\n> - for, to be used by various other commands (e.g. `request-pull`).\n> + for, to be used by various other commands (e.g. `format-patch`\n> + and `request-pull`). Multi-line explanations may be used.\n>\n\nAre these the only locations? Just want to make sure while we're updating it.\n\nOtherwise, for what it's worth...\n\nAcked-by: Jacob Keller \n\nRegards,\nJake\n"},{"id":"269912","messageId":"DDA818BA5B3749C8953193DEC3682293@PhilipOakley","threadId":"40318","inReplyTo":"CA+P7+xqh0e+2aMZf8i-1hBc0fMgaz0UjVdboLv+L9+rBYBR85w@mail.gmail.com","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-14T12:01:00Z","receivedAt":"2015-09-14T12:01:00Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jacob Keller\" \n> Hi,\n>\n> On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley \n> wrote:\n>> The branch description will be included in 'git format-patch\n>> --cover-letter' and in 'git pull-request' emails. Tell the reader.\n>>\n>> While here, clarify that the description may be a multi-line\n>> explanation of the purpose of the branch's patch series.\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>>\n>> This is a short doc patch to follow up $gmane/277628 where Johannes\n>> Schindelin noted this otherwise undocumented feature.\n>>\n>\n> Thanks for this.\n>\n>>\n>> Documentation/git-branch.txt | 3 ++-\n>> Documentation/git-format-patch.txt | 2 +-\n>> Documentation/git-request-pull.txt | 3 ++-\n>> 3 files changed, 5 insertions(+), 3 deletions(-)\n>>\n>> diff --git a/Documentation/git-branch.txt \n>> b/Documentation/git-branch.txt\n>> index a67138a..79ad1c7 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -197,7 +197,8 @@ start-point is either a local or remote-tracking \n>> branch.\n>>\n>> --edit-description::\n>> Open an editor and edit the text to explain what the branch \n>> is\n>> - for, to be used by various other commands (e.g. \n>> `request-pull`).\n>> + for, to be used by various other commands (e.g. \n>> `format-patch`\n>> + and `request-pull`). Multi-line explanations may be used.\n>>\n>\n> Are these the only locations? Just want to make sure while we're \n> updating it.\n\nSearching for 'description' has many hits so it's not easy to be really \nsure. I had thought I'd asked an SO question ($SO/q/6866838) about \nbranch descriptions many years ago, whose answers indicated it was \nlittle used, but actually I'd asked about the repo description (doh) \nwhich AFAICT is only used by gitweb.\n\nA bit more delving found http://stackoverflow.com/a/8858853/717355 which \nsuggests `git merge` would use it, but with no mention in the `git \nmerge --help` man page. A link to the `git fmt-merge-msg` (\"for internal \nuse by scripts\") finally provides the extra:\n\nmerge.branchdesc\n\nIn addition to branch names, populate the log message with the branch \ndescription text associated with them. Defaults to false.\n\nHowever, that config key isn't listed in `git config --help` man page, \nso that capability is a bit buried. (note the default!)\n\n\n\nIt still means that my patch is incomplete in its aim to bring out these \npossible broader usages.\n\n\nI haven't yet looked at the mail archives to see if there is more around \nthe time of those introductions.\n\n>\n> Otherwise, for what it's worth...\n>\n> Acked-by: Jacob Keller \n>\nFor the future, it would also be nice to allow some use within `git \nbranch` for a `--show[-full]-description` option such that when branch \ninfo is being given (-a, -l, etc), then the descriptions for the local \nbranches (which may have descriptions) are displayed, either as a single \nfirst line, or as a full multi-line description. But that's coding & \nreview for the future. \n"},{"id":"269915","messageId":"114A566297E948AFA2962DB352AD46A8@PhilipOakley","threadId":"40318","inReplyTo":"DDA818BA5B3749C8953193DEC3682293@PhilipOakley","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-14T13:24:09Z","receivedAt":"2015-09-14T13:24:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Philip Oakley\" \n> From: \"Jacob Keller\" \n>> Hi,\n>>\n>> On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley \n>> wrote:\n>>> The branch description will be included in 'git format-patch\n>>> --cover-letter' and in 'git pull-request' emails. Tell the reader.\n[...]\n>> Are these the only locations? Just want to make sure while we're \n>> updating it.\n>\n> A bit more delving found http://stackoverflow.com/a/8858853/717355 \n> which suggests `git merge` would use it, but with no mention in the \n> `git merge --help` man page. A link to the `git fmt-merge-msg` (\"for \n> internal use by scripts\") finally provides the extra:\n>\n> merge.branchdesc\n>\n> In addition to branch names, populate the log message with the branch \n> description text associated with them. Defaults to false.\n>\n> However, that config key isn't listed in `git config --help` man page, \n> so that capability is a bit buried. (note the default!)\n\nThis is incorrect. It was fixed in fc0aa39 (Documentation: include \n'merge.branchdesc' for merge and config as well, 2015-05-27), but my \nlocal docs hadn't included it.\n\n>\n> It still means that my patch is incomplete in its aim to bring out \n> these possible broader usages.\n>\ni.e. mentioning 'merge' as a command that uses the branch description, \nand noting it within the merge pages.\n"},{"id":"269925","messageId":"1442239853-4856-1-git-send-email-philipoakley@iee.org","threadId":"40318","inReplyTo":"1442098288-3316-1-git-send-email-philipoakley@iee.org","subject":"[PATCH v2] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-14T14:10:53Z","receivedAt":"2015-09-14T14:10:53Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The branch description will be included in 'git format-patch\n--cover-letter' and in 'git pull-request' emails. It can also\nbe used in the automatic merge message. Tell the reader.\n\nWhile here, clarify that the description may be a multi-line\nexplanation of the purpose of the branch's patch series.\n\nSigned-off-by: Philip Oakley \n---\nfc0aa39 (Documentation: include 'merge.branchdesc' for merge\nand config as well, 2015-05-27) recently added details of the\nlow level config flag.\n\nChanges since V1: discovered that git merge can also include\nthe branch description if enabled, so added a minimal mention to\nflag it to the reader. \n---\n Documentation/git-branch.txt | 4 +++-\n Documentation/git-format-patch.txt | 2 +-\n Documentation/git-merge.txt | 2 +-\n Documentation/git-request-pull.txt | 3 ++-\n 4 files changed, 7 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex a67138a..bbbade4 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -197,7 +197,9 @@ start-point is either a local or remote-tracking branch.\n \n --edit-description::\n \tOpen an editor and edit the text to explain what the branch is\n-\tfor, to be used by various other commands (e.g. `request-pull`).\n+\tfor, to be used by various other commands (e.g. `format-patch`,\n+\t`request-pull`, and `merge` (if enabled)). Multi-line explanations\n+\tmay be used.\n \n --contains []::\n \tOnly list branches which contain the specified commit (HEAD\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 0dac4e9..4035649 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -213,7 +213,7 @@ feeding the result to `git send-email`.\n \n --[no-]cover-letter::\n \tIn addition to the patches, generate a cover letter file\n-\tcontaining the shortlog and the overall diffstat. You can\n+\tcontaining the branch description, shortlog and the overall diffstat. You can\n \tfill in a description in the file before sending it out.\n \n --notes[=]::\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 273a100..a62d672 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -78,7 +78,7 @@ will be appended to the specified message.\n +\n The 'git fmt-merge-msg' command can be\n used to give a good default for automated 'git merge'\n-invocations.\n+invocations. The automated message can include the branch description.\n \n --[no-]rerere-autoupdate::\n \tAllow the rerere mechanism to update the index with the\ndiff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt\nindex 283577b..c32cb0b 100644\n--- a/Documentation/git-request-pull.txt\n+++ b/Documentation/git-request-pull.txt\n@@ -14,7 +14,8 @@ DESCRIPTION\n -----------\n \n Generate a request asking your upstream project to pull changes into\n-their tree. The request, printed to the standard output, summarizes\n+their tree. The request, printed to the standard output,\n+begins with the branch description, summarizes\n the changes and indicates from where they can be pulled.\n \n The upstream project is expected to have the commit named by\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"269935","messageId":"xmqqh9mxx7fk.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"DDA818BA5B3749C8953193DEC3682293@PhilipOakley","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-09-14T17:00:15Z","receivedAt":"2015-09-14T17:00:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> It still means that my patch is incomplete in its aim to bring out\n> these possible broader usages.\n>\n> I haven't yet looked at the mail archives to see if there is more\n> around the time of those introductions.\n\nI guess this is largely my fault, but I think \"git grep\" is an\neasier source of truth to work with than the list archive.\n\nIt eventually boils down to branch.*.description configuration and\nall users of that would call read_branch_desc(), so if you check\ncallers of that helper function and see which commit introduced that\ncall for what purpose (\"blame\" is your friend), you would know how\nthey use the information under what condition.\n\n\n$ git grep -n read_branch_desc -- \\*.c\nbranch.c:143:int read_branch_desc(struct strbuf *buf, const char *branch_name)\nbuiltin/branch.c:771: read_branch_desc(&buf, branch_name);\nbuiltin/fmt-merge-msg.c:211: if (!read_branch_desc(&desc, name)) {\nbuiltin/log.c:888: read_branch_desc(&desc, branch_name);\n\n$ git blame -L210,212 -s builtin/fmt-merge-msg.c\n898eacd8 210) \n898eacd8 211) if (!read_branch_desc(&desc, name)) {\n898eacd8 212) const char *bp = desc.buf;\n\n$ git show -s 898eacd8\ncommit 898eacd8ada2d012f977948350ed60845e238037\nAuthor: Junio C Hamano \nDate: Thu Oct 6 23:12:09 2011 -0700\n\n fmt-merge-msg: use branch.$name.description\n \n This teaches \"merge --log\" and fmt-merge-msg to use branch description\n information when merging a local topic branch into the mainline. The\n description goes between the branch name label and the list of commit\n titles.\n \n The refactoring to share the common configuration parsing between\n merge and fmt-merge-msg needs to be made into a separate patch.\n \n Signed-off-by: Junio C Hamano \n\netc. etc.\n"},{"id":"270076","messageId":"9075C82973D34EABBB96023B75D6848E@PhilipOakley","threadId":"40318","inReplyTo":"xmqqh9mxx7fk.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-15T16:06:27Z","receivedAt":"2015-09-15T16:06:27Z","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>> It still means that my patch is incomplete in its aim to bring out\n>> these possible broader usages.\n>>\n>> I haven't yet looked at the mail archives to see if there is more\n>> around the time of those introductions.\n>\n> I guess this is largely my fault, but I think \"git grep\" is an\n> easier source of truth to work with than the list archive.\n>\n> It eventually boils down to branch.*.description configuration and\n> all users of that would call read_branch_desc(), so if you check\n> callers of that helper function and see which commit introduced that\n> call for what purpose (\"blame\" is your friend), you would know how\n> they use the information under what condition.\n>\n>\n> $ git grep -n read_branch_desc -- \\*.c\n> branch.c:143:int read_branch_desc(struct strbuf *buf, const char\n> *branch_name)\n> builtin/branch.c:771: read_branch_desc(&buf, branch_name);\n> builtin/fmt-merge-msg.c:211: if (!read_branch_desc(&desc, name)) {\n> builtin/log.c:888: read_branch_desc(&desc, branch_name);\n>\n> $ git blame -L210,212 -s builtin/fmt-merge-msg.c\n> 898eacd8 210)\n> 898eacd8 211) if (!read_branch_desc(&desc, name)) {\n> 898eacd8 212) const char *bp = desc.buf;\n>\n> $ git show -s 898eacd8\n> commit 898eacd8ada2d012f977948350ed60845e238037\n> Author: Junio C Hamano \n[...]>\n> Signed-off-by: Junio C Hamano \n>\n> etc. etc.\n\n---\nThanks.\nThat was very useful seeing a few more of the options in combination.\nThat, combined with the updated G4W, is a lot better/faster.\n\nI've also searched for:\n$ git grep -n \"\\.description\" -- \\*.sh\n\nwhich only came up with\ngit-request-pull.sh:74: ! git config \"branch.$branch_name.description\" \n >/dev/null\ngit-request-pull.sh:156: git config \"branch.$branch_name.description\"\n\nas relevant hits:\n\nSometimes one can be a bit feart to try out some command options..\n\nPhilip\n"},{"id":"270077","messageId":"FC4CBDCF8B7649B7B1C2342D6ADC8DF2@PhilipOakley","threadId":"40318","inReplyTo":"xmqqh9mxx7fk.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: show usage of branch description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-09-15T19:10:08Z","receivedAt":"2015-09-15T19:10:08Z","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>> It still means that my patch is incomplete in its aim to bring out\n>> these possible broader usages.\n>>\n>> I haven't yet looked at the mail archives to see if there is more\n>> around the time of those introductions.\n>\n> I guess this is largely my fault, but I think \"git grep\" is an\n> easier source of truth to work with than the list archive.\n>\n> It eventually boils down to branch.*.description configuration and\n> all users of that would call read_branch_desc(), so if you check\n> callers of that helper function and see which commit introduced that\n> call for what purpose (\"blame\" is your friend), you would know how\n> they use the information under what condition.\n>\n>\n> $ git grep -n read_branch_desc -- \\*.c\n> branch.c:143:int read_branch_desc(struct strbuf *buf, const char\n> *branch_name)\n> builtin/branch.c:771: read_branch_desc(&buf, branch_name);\n> builtin/fmt-merge-msg.c:211: if (!read_branch_desc(&desc, name)) {\n> builtin/log.c:888: read_branch_desc(&desc, branch_name);\n>\n> $ git blame -L210,212 -s builtin/fmt-merge-msg.c\n> 898eacd8 210)\n> 898eacd8 211) if (!read_branch_desc(&desc, name)) {\n> 898eacd8 212) const char *bp = desc.buf;\n>\n> $ git show -s 898eacd8\n> commit 898eacd8ada2d012f977948350ed60845e238037\n> Author: Junio C Hamano \n[...]>\n> Signed-off-by: Junio C Hamano \n>\n> etc. etc.\n\n---\nThanks.\nThat was very useful seeing a few more of the options in combination.\nThat, combined with the updated G4W, is a lot better/faster.\nSometimes one can be a bit feart to try out some command options..\n\n\nI've also searched for:\n\n$ git grep -n \"\\.description\" -- \\*.sh\n\nwhich only came up with\n\ngit-request-pull.sh:74: ! git config \"branch.$branch_name.description\" \n >/dev/null\ngit-request-pull.sh:156: git config \"branch.$branch_name.description\"\n\nas relevant hits.\n\nPhilip\n"},{"id":"270274","messageId":"CAPnjgZ1z8UakVy2D8CVuTCdvB6hhYDPJXQk9QBp66hQ1rxrKDA@mail.gmail.com","threadId":"40318","inReplyTo":"CAFOYHZB3dKgi3rERHXuWynTjYQu+iPVdbWqmtoD+irYopfoRCg@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Simon Glass","fromEmail":"sjg@chromium.org","sentAt":"2015-09-18T04:03:06Z","receivedAt":"2015-09-18T04:03:06Z","isPatch":false,"sender":{"key":"sjg@chromium.org","avatar":null},"body":"Hi Jacob,\n\nOn 11 September 2015 at 02:30, Chris Packham wrote:\n> On Fri, Sep 11, 2015 at 4:28 AM, Jacob Keller wrote:\n>> Hey,\n>>\n>> does anyone know of any tricks for storing a cover letter for a patch\n>> series inside of git somehow? I'd guess the only obvious way currently\n>> is to store it at the top of the series as an empty commit.. but this\n>> doesn't get emailed *as* the cover letter...\n>>\n>> Is there some other way? Would others be interested in such a feature?\n>>\n>> I get very annoyed when I've written a nice long patch cover letter in\n>> vim before an email and then realize I should fix something else up,\n>> or accidentally cancel it because I didn't use the write \"To:\" address\n>> or something..\n>>\n>> I really think it should be possible to store something somehow as a\n>> blob that could be looked up later. Even if this was a slightly more\n>> manual process that would be helpful to store the message inside git\n>> itself.\n>>\n>> In addition, this would help re-rolls since it would mean if I go back\n>> to a topic and re-roll it I can just update the message. If it were\n>> properly stored in my local history that would also mean I could see\n>> revisions on it.\n>>\n>> Any thoughts on how to do this?\n>>\n>\n> A bit of a plug for patman[1] which the u-boot project uses (although\n> there's nothing u-boot specific about it). It lets you put the cover\n> letter and other meta information in the commit messages as you go\n> then will extract that information and generate a cover letter and\n> clean patches. As of fairly recently it's also installable as a\n> standalone application.\n>\n> --\n> [1] - http://git.denx.de/?p=u-boot.git;a=blob;f=tools/patman/README\n\nIf you do end up trying it out I'd appreciate any feedback you have.\nI've sent 1000s of patches through it over the past few years.\n\nRegards,\nSimon\n"},{"id":"293157","messageId":"20160805024032-mutt-send-email-mst@kernel.org","threadId":"40318","inReplyTo":"CA+P7+xq2H-ZRix_71bQdswuEm++64ZA8FmK7J+1jhUhFeCZbgg@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Michael S. Tsirkin","fromEmail":"mst@redhat.com","sentAt":"2016-08-04T23:43:11Z","receivedAt":"2016-08-04T23:43:18Z","isPatch":false,"sender":{"key":"mst@kernel.org","avatar":null},"body":"On Thu, Sep 10, 2015 at 02:03:48PM -0700, Jacob Keller wrote:\n> On Thu, Sep 10, 2015 at 1:09 PM, Philip Oakley wrote:\n> > From: \"Jacob Keller\" \n> >>\n> >> On Thu, Sep 10, 2015 at 11:44 AM, Junio C Hamano \n> >> wrote:\n> >>>\n> >>> Jacob Keller writes:\n> >>>\n> >>>> I hadn't thought of separating the cover letter from git-send-email.\n> >>>> That would be suitable for me.\n> >>>\n> >>>\n> >>> Yeah, I said this number of times over time, and I said it once\n> >>> recently in another thread, but I think it was a mistake to allow\n> >>> git-send-email to drive format-patch. It may appear that it will\n> >>> make things convenient in the perfect world where no user makes\n> >>> mistakes, but people are not perfect in real life. Expecting them\n> >>> to be is being naive.\n> >>>\n> >>\n> >> Yep. I didn't even know cover-letter was an option of format-patch\n> >> only thought it was in send-email.\n> >>\n> > Actually, the one feature I'd like (I think) is to be able to join together\n> > the empty commit mechanism and the cover letter mechanism within format\n> > patch so that:\n> >\n> > * the empty commit message would detected and automatically become the [0/N]\n> > in the patch series (without need to say --cover-letter)\n> >\n> > * the cover letter would still have some 'template' markings to say \"***\n> > insert what's changed here***\" or smilar (with option to exclude them).\n> >\n> > That way, when starting a series / branch, the first item would be to add\n> > the explanatory 'empty commit' that states the requirements of what one\n> > hopes to achieve (a key cover letter content), which is then followed by\n> > commits that move toward that goal.\n> >\n> > The series can then be rebased as the user develops the code, and that cover\n> > note can be edited as required during the rebase.\n> >\n> > When it comes time to show it to the list, the format patch will *know* from\n> > the empty commit that it is the [0/N] cover letter and (perhaps -option) add\n> > the appropriate markers ready for editing.\n\nAnd perhaps git am could learn an option to apply 0/N\nas a cover commit.\n\n> > The user edits the cover letter with the extra 'what's changed' / interdiff\n> > / whatever, and sends. sendmail barfs if the user hasn't edited the markers.\n> >\n> > This could also work with the sendmail patch formating (though I've never\n> > used that workflow) as now the cover letter becomes automatic for the\n> > upstream.\n> >\n> > Philip\n> \n> If there was a way to store this empty commit message tagged as \"cover\n> letter\" that could work well, though generally I prefer the\n> non-fast-forward merges as this shows you where the series ended *and*\n> began. It's somewhat confusing to newer users.. and this doesn't get\n> rebased very well either.\n> \n> Some way to indicate a particular \"empty\" commit is actually a cover\n> letter seems easy enough. This seems like the way that I was thinking.\n\nStart the subject with \"cover! \"?\nI have a patch that teaches git-rebase to keep empty commits\nwhere the subject has a given prefix, that might be helpful there.\n\n\n> Using \"edit description\" of git-branch seems also to be pretty\n> effective for this, even if it doesn't get shared across remotes. (not\n> really a necessary feature for what I do).\n> \n> But having some way to indicate \"cover letter\" which gets used as the\n> beginning of a log message when doing a particular \"merge\n> --tip-as-cover\" or something like Junio suggested above seems like the\n> nicest approach.\n> \n> Regards,\n> Jake\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"293158","messageId":"20160804234920.GA27250@redhat.com","threadId":"40318","inReplyTo":"xmqqzj0u2k5m.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Michael S. Tsirkin","fromEmail":"mst@redhat.com","sentAt":"2016-08-04T23:49:20Z","receivedAt":"2016-08-04T23:49:39Z","isPatch":false,"sender":{"key":"mst@kernel.org","avatar":null},"body":"On Thu, Sep 10, 2015 at 11:39:49AM -0700, Junio C Hamano wrote:\n> The problem with \"empty commit trick\" is that it is a commit whose\n> sole purpose is to describe the series, and its presence makes it\n> clear where the series ends, but the topology does not tell where\n> the series begins, so it is an unsatisifactory half-measure.\n\nActually, when using topic branches the series always ends at head, so\nit's better to keep the empty commit where series begins.\n\nThis was actually suggested by Philip Oakley on this thread\nbut I'm not sure it was noticed as it was part of a bigger email.\n\nIt also maps much better to git am uses - you apply patch 0/N first to\ncreate the empty commit, then the rest of the patches.\n\nThis does mean you need to use git rebase to edit that cover\ncommit, but maybe that is not a big deal, and git rebase could\nlearn --cover to find and edit that.\n-- \nMST\n"},{"id":"293199","messageId":"xmqqy44bxm0h.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"20160804234920.GA27250@redhat.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-05T15:39:58Z","receivedAt":"2016-08-05T15:40:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Michael S. Tsirkin\" writes:\n\n> On Thu, Sep 10, 2015 at 11:39:49AM -0700, Junio C Hamano wrote:\n>> The problem with \"empty commit trick\" is that it is a commit whose\n>> sole purpose is to describe the series, and its presence makes it\n>> clear where the series ends, but the topology does not tell where\n>> the series begins, so it is an unsatisifactory half-measure.\n>\n> Actually, when using topic branches the series always ends at head, so\n> it's better to keep the empty commit where series begins.\n\nBut that would mean that you would need to destroy and recreate more\ncommits than you would need to. If you have a five-commit series\n(with the bottom \"description\" one, you would have six commits) and\nyou are already happy with the bottom two but want to update the\nthird one, you wuld have to \"rebase -i\" all six of them, reword the\nbottom \"description\" to adjust it to describe the new version of the\nthird one _before_ you even do the actual update of the third one.\n\nThat somehow feels backwards, and that backward-ness comes from the\nfact that you abused a single-parent commit for the purpose it is\nnot meant to be used (i.e. they are to describe individual changes),\nbecause you did not find a better existing mechanism (and I suspect\nthere isn't any, in which case the solution is to invent one, not\nabusing an existing mechanism that is not suited for it).\n\nIf this were part of a workflow like this, I would understand it:\n\n * Build a N-commit series on a topic.\n\n * You keep a \"local integration testing\" branch (\"lit\"), forked\n from a mainline and updated _every time_ you do something to your\n topics. You may or may not publish this branch. This is the\n aggregation of what you locally have done, a convenient place to\n test individual topics together before they get published.\n\n * A new topic, when you merge it to the \"lit\" branch, you describe\n the cover as the merge commit message.\n\n * When you updated an existing topic, you tell a tool like \"rebase\n -i -p\" to recreate \"lit\" branch on top of the mainline. This\n would give you an opportunity to update the cover.\n\nNow the tool support for the last one is the missing piece. In\naddition to what \"rebase -i -p\" would, it at least need to\nautomatically figure out which topics have been updated, so that\ntheir merge commit log messages need to be given in the editor to\nupdate, while carrying over the merge log message for other topics\nintact (by default).\n\nWith that, you should also be able to teach \"format-patch --cover\"\nto take these merge messages on \"lit\" into account when it creates\nthe cover letter.\n"},{"id":"293245","messageId":"10752620.2J2dEZLIGc@mfick1-lnx","threadId":"40318","inReplyTo":"xmqqy44bxm0h.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Martin Fick","fromEmail":"mfick@codeaurora.org","sentAt":"2016-08-05T21:20:00Z","receivedAt":"2016-08-05T21:20:15Z","isPatch":false,"sender":{"key":"mfick@codeaurora.org","avatar":null},"body":"On Friday, August 05, 2016 08:39:58 AM you wrote:\n> * A new topic, when you merge it to the \"lit\" branch, you\n> describe the cover as the merge commit message.\n> \n> * When you updated an existing topic, you tell a tool\n> like \"rebase -i -p\" to recreate \"lit\" branch on top of\n> the mainline. This would give you an opportunity to\n> update the cover.\n\nThis is a neat idea. How would this work if there is no \nmerge commit (mainline hasn't moved)?\n\n-Martin\n\n-- \nThe Qualcomm Innovation Center, Inc. is a member of Code \nAurora Forum, hosted by The Linux Foundation\n\n"},{"id":"293248","messageId":"CAPc5daV51cwPs-8uc_SYLaod7RB7aDGYbjt-x-JsY1qNL81QRA@mail.gmail.com","threadId":"40318","inReplyTo":"10752620.2J2dEZLIGc@mfick1-lnx","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-05T21:23:42Z","receivedAt":"2016-08-05T21:24:33Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"On Fri, Aug 5, 2016 at 2:20 PM, Martin Fick wrote:\n> On Friday, August 05, 2016 08:39:58 AM you wrote:\n>> * A new topic, when you merge it to the \"lit\" branch, you\n>> describe the cover as the merge commit message.\n>>\n>> * When you updated an existing topic, you tell a tool\n>> like \"rebase -i -p\" to recreate \"lit\" branch on top of\n>> the mainline. This would give you an opportunity to\n>> update the cover.\n>\n> This is a neat idea. How would this work if there is no\n> merge commit (mainline hasn't moved)?\n\nSorry, I do not understand your question. You always\nmerge into your own \"lit\", which is based on (some)\nversion of the mainline. If a topic builds on top of the\nmainline, you \"merge --no-ff\" it into \"lit\". Because no\nmerges on \"lit\" will be part of the future mainline anyway,\neven the project frowns upon a \"no-ff\" merge, that will\nnot be a problem.\n"},{"id":"293281","messageId":"xmqqziopj0x6.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CAPc5daV51cwPs-8uc_SYLaod7RB7aDGYbjt-x-JsY1qNL81QRA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-06T16:51:33Z","receivedAt":"2016-08-06T20:10:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> On Fri, Aug 5, 2016 at 2:20 PM, Martin Fick wrote:\n>> On Friday, August 05, 2016 08:39:58 AM you wrote:\n>>> * A new topic, when you merge it to the \"lit\" branch, you\n>>> describe the cover as the merge commit message.\n>>>\n>>> * When you updated an existing topic, you tell a tool\n>>> like \"rebase -i -p\" to recreate \"lit\" branch on top of\n>>> the mainline. This would give you an opportunity to\n>>> update the cover.\n>>\n>> This is a neat idea. How would this work if there is no\n>> merge commit (mainline hasn't moved)?\n>\n> Sorry, I do not understand your question. You always\n> merge into your own \"lit\", which is based on (some)\n> version of the mainline. If a topic builds on top of the\n> mainline, you \"merge --no-ff\" it into \"lit\". Because no\n> merges on \"lit\" will be part of the future mainline anyway,\n> even the project frowns upon a \"no-ff\" merge, that will\n> not be a problem.\n\nIn any case, the \"if you want to say more than what the individual\ncommits say about the topic as a whole, say it in the merge that\nbrings them all into an integration branch\" is not just \"a neat\nidea\". \n\nRecent versions of Git actively _encourages_ you to describe what it\nis about by opening your editor when you create a merge, and the\ncover letter material is something you would want the merge of your\ntopic into the upstream to say when your topic finally lands there.\nAnd as the author of a topic, the person who writes the cover letter\nis well qualified to describe what the topic as a whole is about,\nhow it relates to the state of the entire project before that merge\nhappens. That is what you want to write in the cover letter.\n\nSo \"write it in a merge log message yourself, and somehow find a way\nto propagate it to the maintainer's tree\" is the natural consequence\nof thinking and working backwards from what we want to have in the\nfinal history; not any novel (or neat) idea.\n\nWhat follows is that at the receiving end (i.e. \"git am\") it may be\nsuboptimal to create an empty commit to record the cover letter\nmaterial. Storing at the bottom of the received pile of commits is\nout of question. It _might_ be acceptable to queue it as the tip,\nand then teach \"git merge $topic\" to notice that $topic^0 is such a\n\"cover letter commit\", and turn itself into \"git merge $topic^1 &&\ngit commit --amend -C $topic\", though.\n"},{"id":"293313","messageId":"20160807080857-mutt-send-email-mst@kernel.org","threadId":"40318","inReplyTo":"xmqqy44bxm0h.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Michael S. Tsirkin","fromEmail":"mst@redhat.com","sentAt":"2016-08-07T05:12:23Z","receivedAt":"2016-08-07T05:12:59Z","isPatch":false,"sender":{"key":"mst@kernel.org","avatar":null},"body":"On Fri, Aug 05, 2016 at 08:39:58AM -0700, Junio C Hamano wrote:\n> \"Michael S. Tsirkin\" writes:\n> \n> > On Thu, Sep 10, 2015 at 11:39:49AM -0700, Junio C Hamano wrote:\n> >> The problem with \"empty commit trick\" is that it is a commit whose\n> >> sole purpose is to describe the series, and its presence makes it\n> >> clear where the series ends, but the topology does not tell where\n> >> the series begins, so it is an unsatisifactory half-measure.\n> >\n> > Actually, when using topic branches the series always ends at head, so\n> > it's better to keep the empty commit where series begins.\n> \n> But that would mean that you would need to destroy and recreate more\n> commits than you would need to. If you have a five-commit series\n> (with the bottom \"description\" one, you would have six commits) and\n> you are already happy with the bottom two but want to update the\n> third one, you wuld have to \"rebase -i\" all six of them, reword the\n> bottom \"description\" to adjust it to describe the new version of the\n> third one _before_ you even do the actual update of the third one.\n> \n> That somehow feels backwards, and that backward-ness comes from the\n> fact that you abused a single-parent commit for the purpose it is\n> not meant to be used (i.e. they are to describe individual changes),\n> because you did not find a better existing mechanism (and I suspect\n> there isn't any, in which case the solution is to invent one, not\n> abusing an existing mechanism that is not suited for it).\n\nA flag that marks a commit \"beginning of series\" then?\n\n> If this were part of a workflow like this, I would understand it:\n> \n> * Build a N-commit series on a topic.\n> \n> * You keep a \"local integration testing\" branch (\"lit\"), forked\n> from a mainline and updated _every time_ you do something to your\n> topics. You may or may not publish this branch. This is the\n> aggregation of what you locally have done, a convenient place to\n> test individual topics together before they get published.\n\nThis seems to assume topic branches. I know you use them,\nbut not overyone does, I don't.\n\n> * A new topic, when you merge it to the \"lit\" branch, you describe\n> the cover as the merge commit message.\n> \n> * When you updated an existing topic, you tell a tool like \"rebase\n> -i -p\" to recreate \"lit\" branch on top of the mainline. This\n> would give you an opportunity to update the cover.\n\nCombining patchsets might need conflict resolution,\nredoing this each time might be a lot of work.\n\n> Now the tool support for the last one is the missing piece. In\n> addition to what \"rebase -i -p\" would, it at least need to\n> automatically figure out which topics have been updated, so that\n> their merge commit log messages need to be given in the editor to\n> update, while carrying over the merge log message for other topics\n> intact (by default).\n> \n> With that, you should also be able to teach \"format-patch --cover\"\n> to take these merge messages on \"lit\" into account when it creates\n> the cover letter.\n"},{"id":"293321","messageId":"20160807095216.sdvofyz5qhdej35n@john.keeping.me.uk","threadId":"40318","inReplyTo":"20160807080857-mutt-send-email-mst@kernel.org","subject":"Re: storing cover letter of a patch series?","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2016-08-07T09:52:16Z","receivedAt":"2016-08-07T09:52:41Z","isPatch":false,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Sun, Aug 07, 2016 at 08:12:23AM +0300, Michael S. Tsirkin wrote:\n> On Fri, Aug 05, 2016 at 08:39:58AM -0700, Junio C Hamano wrote:\n> > * When you updated an existing topic, you tell a tool like \"rebase\n> > -i -p\" to recreate \"lit\" branch on top of the mainline. This\n> > would give you an opportunity to update the cover.\n> \n> Combining patchsets might need conflict resolution,\n> redoing this each time might be a lot of work.\n\ngit-rerere can generally handle that pretty well. I wrote a tool [1] to\nmanage integration branches which I use pretty heavily and I find it\nvery rare to hit a serious conflict. In fact, git-integration has an\n\"autocontinue\" mode which accepts git-rerere's resolution if it has one,\nwhich works reliably in my experience.\n\nI hadn't thought about writing the cover letter in the integration\nbranch instruction sheet (I normally just put in some notes for myself\nabout the state of the branch), but I suspect it would be quite easy to\nwrite a script that mails a series using the instruction sheet comments\nas the cover letter.\n\n[1] http://johnkeeping.github.io/git-integration/\n"},{"id":"293322","messageId":"CACsJy8DhDMkmq-WCVHSMYVTTfEXNFUUzz5Cq9hQj_tGRUTj3ZA@mail.gmail.com","threadId":"40318","inReplyTo":"20160807080857-mutt-send-email-mst@kernel.org","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-07T10:42:06Z","receivedAt":"2016-08-07T10:42:42Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sun, Aug 7, 2016 at 7:12 AM, Michael S. Tsirkin wrote:\n> On Fri, Aug 05, 2016 at 08:39:58AM -0700, Junio C Hamano wrote:\n>> \"Michael S. Tsirkin\" writes:\n>>\n>> > On Thu, Sep 10, 2015 at 11:39:49AM -0700, Junio C Hamano wrote:\n>> >> The problem with \"empty commit trick\" is that it is a commit whose\n>> >> sole purpose is to describe the series, and its presence makes it\n>> >> clear where the series ends, but the topology does not tell where\n>> >> the series begins, so it is an unsatisifactory half-measure.\n>> >\n>> > Actually, when using topic branches the series always ends at head, so\n>> > it's better to keep the empty commit where series begins.\n>>\n>> But that would mean that you would need to destroy and recreate more\n>> commits than you would need to. If you have a five-commit series\n>> (with the bottom \"description\" one, you would have six commits) and\n>> you are already happy with the bottom two but want to update the\n>> third one, you wuld have to \"rebase -i\" all six of them, reword the\n>> bottom \"description\" to adjust it to describe the new version of the\n>> third one _before_ you even do the actual update of the third one.\n>>\n>> That somehow feels backwards, and that backward-ness comes from the\n>> fact that you abused a single-parent commit for the purpose it is\n>> not meant to be used (i.e. they are to describe individual changes),\n>> because you did not find a better existing mechanism (and I suspect\n>> there isn't any, in which case the solution is to invent one, not\n>> abusing an existing mechanism that is not suited for it).\n>\n> A flag that marks a commit \"beginning of series\" then?\n\ngit-notes was mentioned in this thread back in 2015, but I think it's\ndiscarded because of the argument that's part of the cover letter was\nnot meant to be kept permanently. But I think we can still use it as a\nlocal/temporary place for cover letter instead of the empty commit at\nthe topic's tip. It is a mark of the beginning of commit, it does not\nrequire rewriting history when you update the cover letter, and\ngit-merge can be taught to pick it up when you're ready to set it in\nstone.\n-- \nDuy\n"},{"id":"293368","messageId":"CAGZ79kba36GprgHA04_q4NmY2=_amoWyafUaLKkcknc3HsT_-g@mail.gmail.com","threadId":"40318","inReplyTo":"CA+P7+xpHDGY5RTR8ntrABdxqM6b4V9dndS68=kV1+1Ym1N6YKw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-08T17:27:18Z","receivedAt":"2016-08-08T17:27:24Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Thu, Sep 10, 2015 at 9:28 AM, Jacob Keller wrote:\n> Hey,\n>\n> does anyone know of any tricks for storing a cover letter for a patch\n> series inside of git somehow? I'd guess the only obvious way currently\n> is to store it at the top of the series as an empty commit.. but this\n> doesn't get emailed *as* the cover letter...\n>\n> Is there some other way? Would others be interested in such a feature?\n\nBeing late to this thread, but I think\n\n branch..description\n Branch description, can be edited with git branch\n --edit-description. Branch description is automatically added in\n the format-patch cover letter or request-pull summary.\n\nis what you want. Maybe we want to see a patch that adds the reverse\nfunctionality as well, i.e. git-am will store the the cover letter as the\nbranch description and git-merge will propose the branch description for\nthe merge commit.\n\n>\n> I get very annoyed when I've written a nice long patch cover letter in\n> vim before an email and then realize I should fix something else up,\n> or accidentally cancel it because I didn't use the write \"To:\" address\n> or something..\n>\n> I really think it should be possible to store something somehow as a\n> blob that could be looked up later. Even if this was a slightly more\n> manual process that would be helpful to store the message inside git\n> itself.\n\nI agree here. I personally do not use that variable (yet), as it doesn't seem\nto be editable easily.\nSo here is what I do:\n1) First series is generated with format-patch --cover-letter\n2) any following v{2,3,4} is generated without the cover-letter but with\n --subject-prefix=PATCHv{2,3,4}\n3) the cover letter is manually edited to be the next version and a section\n is added why the next version of the series is sent.\n\n>\n> In addition, this would help re-rolls since it would mean if I go back\n> to a topic and re-roll it I can just update the message. If it were\n> properly stored in my local history that would also mean I could see\n> revisions on it.\n>\n> Any thoughts on how to do this?\n>\n> Regards,\n> Jake\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"293370","messageId":"xmqqmvknf986.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CACsJy8DhDMkmq-WCVHSMYVTTfEXNFUUzz5Cq9hQj_tGRUTj3ZA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-08T17:42:33Z","receivedAt":"2016-08-08T17:42:41Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> git-notes was mentioned in this thread back in 2015, but I think it's\n> discarded because of the argument that's part of the cover letter was\n> not meant to be kept permanently.\n\nI do not think the reason why we didn't think the notes mechanism\nwas a good match was mainly because the cover letter material was\nabout a branch as a whole, which does not have a good counter-part\nin Git at the conceptual level. \"A branch is just a moving pointer\nthat points at one commit that happens to be at the tip\" is not a\nperfect match to \"I am holding these N patches to achieve X and I am\nconstantly adding, rewinding and rebuilding\". The notes mechanism\ngives an easy way to describe the former (i.e. annotate one commit,\nand let various commands to move that notes as you rewind and\nrebuild) but not the latter (i.e. \"branch.description\" configuration\nis the best match, but that is just a check-box feature and does not\nmake any serious attempt to be part of a version-control system).\n\n> But I think we can still use it as a\n> local/temporary place for cover letter instead of the empty commit at\n> the topic's tip. It is a mark of the beginning of commit, it does not\n> require rewriting history when you update the cover letter, and\n> git-merge can be taught to pick it up when you're ready to set it in\n> stone.\n\nThat depends on what you exactly mean by \"the beginning of\". Do you\nmean the first commit that is on the topic? Then that still requires\nyou to move it around when the topic is rebuilt. If you mean the\ncommit on the mainline the topic forks from, then of course that\nwould not work, as you can fork multiple topics at the same commit.\n\n\n"},{"id":"293387","messageId":"xmqqk2frdnud.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CAGZ79kba36GprgHA04_q4NmY2=_amoWyafUaLKkcknc3HsT_-g@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-08T20:09:46Z","receivedAt":"2016-08-08T20:09:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stefan Beller writes:\n\n> On Thu, Sep 10, 2015 at 9:28 AM, Jacob Keller wrote:\n>> Hey,\n>>\n>> does anyone know of any tricks for storing a cover letter for a patch\n>> series inside of git somehow? I'd guess the only obvious way currently\n>> is to store it at the top of the series as an empty commit.. but this\n>> doesn't get emailed *as* the cover letter...\n>>\n>> Is there some other way? Would others be interested in such a feature?\n>\n> Being late to this thread, but I think\n>\n> branch..description\n> Branch description, can be edited with git branch\n> --edit-description. Branch description is automatically added in\n> the format-patch cover letter or request-pull summary.\n>\n> is what you want. Maybe we want to see a patch that adds the reverse\n> functionality as well, i.e. git-am will store the the cover letter as the\n> branch description and git-merge will propose the branch description for\n> the merge commit.\n\nYes, but... ;-) It is a bit too weak to be called a proper part of\na \"version control system\", in that the description, even though it\ncan be edited with \"--edit-description\", is not versioned.\n\nIt is consistent with the fact that rerolls of your branch by\nrebuilding with \"rebase -i\" or \"checkout --detached && until\nsatisified; do cherry-pick && commit --amend; done\" is not versioned\nand you may resort to the old-fashioned my-topic, my-topic-v2,\nmy-topic-v3, ..., but being consistent with a bad part of the system\ndoes not deny the fact that it is a weak feature.\n"},{"id":"293460","messageId":"70b74f2e-3870-4bef-1664-1c2dd05eda96@drmicha.warpmail.net","threadId":"40318","inReplyTo":"xmqqmvknf986.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2016-08-09T07:12:54Z","receivedAt":"2016-08-09T07:23:08Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 08.08.2016 19:42:\n> Duy Nguyen writes:\n> \n>> git-notes was mentioned in this thread back in 2015, but I think it's\n>> discarded because of the argument that's part of the cover letter was\n>> not meant to be kept permanently.\n> \n> I do not think the reason why we didn't think the notes mechanism\n> was a good match was mainly because the cover letter material was\n> about a branch as a whole, which does not have a good counter-part\n> in Git at the conceptual level. \"A branch is just a moving pointer\n> that points at one commit that happens to be at the tip\" is not a\n> perfect match to \"I am holding these N patches to achieve X and I am\n> constantly adding, rewinding and rebuilding\". The notes mechanism\n> gives an easy way to describe the former (i.e. annotate one commit,\n> and let various commands to move that notes as you rewind and\n> rebuild) but not the latter (i.e. \"branch.description\" configuration\n> is the best match, but that is just a check-box feature and does not\n> make any serious attempt to be part of a version-control system).\n> \n>> But I think we can still use it as a\n>> local/temporary place for cover letter instead of the empty commit at\n>> the topic's tip. It is a mark of the beginning of commit, it does not\n>> require rewriting history when you update the cover letter, and\n>> git-merge can be taught to pick it up when you're ready to set it in\n>> stone.\n> \n> That depends on what you exactly mean by \"the beginning of\". Do you\n> mean the first commit that is on the topic? Then that still requires\n> you to move it around when the topic is rebuilt. If you mean the\n> commit on the mainline the topic forks from, then of course that\n> would not work, as you can fork multiple topics at the same commit.\n\nWell, my idea back then was: attach notes to refs rather than commits,\nin this case to the branch ref. That would solve both the \"branch moves\"\nas well as the \"cover letter refers to the whole branch/topic\" issues.\n\nIn fact, I had an implementation that I had been rebasing and using for\nquite some time, but it never became popular, and branch.description\nlanded in-tree. [short version: notes attached to (virtual) refname\nobjects (virtual blobs - not stored, but \"existing\" for (fsck, notes\nprune and the like)]\n\nThe notes based approach suffered from the old notes deficiency: we\ndon't have good simple tooling for sharing notes; really, we don't have\ngood tooling for dealing with any remote refs besides branches (read:\nref namespace reorg project is stalled), unless you set up specific\nrefspecs.\n\n\nOTOH, branch.description is inherently local, too, and can't even be\ntransported after setting up refspecs or such.\n\nAlso, notes trees have a history, so you would gain a log on your cover\nletter edits; again, our tooling around that notes feature is\nsub-optimal, that is: the feature is there, the ui could improve.\n\nMichael\n\n"},{"id":"298952","messageId":"CACsJy8C51UkH=tLSfGigAF0JjPxVS3fY0EHi0CNVRG8LY8YiCg@mail.gmail.com","threadId":"40318","inReplyTo":"CAGZ79kba36GprgHA04_q4NmY2=_amoWyafUaLKkcknc3HsT_-g@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-13T08:49:51Z","receivedAt":"2016-08-13T08:56:14Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Aug 9, 2016 at 12:27 AM, Stefan Beller wrote:\n> On Thu, Sep 10, 2015 at 9:28 AM, Jacob Keller wrote:\n>> Hey,\n>>\n>> does anyone know of any tricks for storing a cover letter for a patch\n>> series inside of git somehow? I'd guess the only obvious way currently\n>> is to store it at the top of the series as an empty commit.. but this\n>> doesn't get emailed *as* the cover letter...\n>>\n>> Is there some other way? Would others be interested in such a feature?\n>\n> Being late to this thread, but I think\n>\n> branch..description\n> Branch description, can be edited with git branch\n> --edit-description. Branch description is automatically added in\n> the format-patch cover letter or request-pull summary.\n>\n> is what you want. Maybe we want to see a patch that adds the reverse\n> functionality as well, i.e. git-am will store the the cover letter as the\n> branch description and git-merge will propose the branch description for\n> the merge commit.\n\nI almost suggested the same, but there is a problem with this\napproach: if you're are on a detached head, where does git-am save it?\n-- \nDuy\n"},{"id":"299258","messageId":"CA+P7+xo4UJ8W4G0gV=DMLs-9Ve4v0OKc0ZunmS5Y5B1k7L0P9w@mail.gmail.com","threadId":"40318","inReplyTo":"CACsJy8C51UkH=tLSfGigAF0JjPxVS3fY0EHi0CNVRG8LY8YiCg@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-14T07:15:51Z","receivedAt":"2016-08-14T08:52:26Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Sat, Aug 13, 2016 at 1:49 AM, Duy Nguyen wrote:\n> On Tue, Aug 9, 2016 at 12:27 AM, Stefan Beller wrote:\n>> is what you want. Maybe we want to see a patch that adds the reverse\n>> functionality as well, i.e. git-am will store the the cover letter as the\n>> branch description and git-merge will propose the branch description for\n>> the merge commit.\n>\n> I almost suggested the same, but there is a problem with this\n> approach: if you're are on a detached head, where does git-am save it?\n> --\n> Duy\n\nAlso, what about the case where a branch already has a description\nsuch as is the case for something other than an integration branch.\nHow does git-am know the difference and ensure it doesn't overwrite\nanything? Not everyone uses separate branches for each patch and such.\n\nThanks,\nJake\n"},{"id":"299316","messageId":"CAGZ79kb27JZepMD5AmrHjOnf8haE8LehZd_CkvOQ1UoLEDuxKQ@mail.gmail.com","threadId":"40318","inReplyTo":"CA+P7+xo4UJ8W4G0gV=DMLs-9Ve4v0OKc0ZunmS5Y5B1k7L0P9w@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-15T06:28:18Z","receivedAt":"2016-08-15T06:28:25Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sun, Aug 14, 2016 at 12:15 AM, Jacob Keller wrote:\n> On Sat, Aug 13, 2016 at 1:49 AM, Duy Nguyen wrote:\n>> On Tue, Aug 9, 2016 at 12:27 AM, Stefan Beller wrote:\n>>> is what you want. Maybe we want to see a patch that adds the reverse\n>>> functionality as well, i.e. git-am will store the the cover letter as the\n>>> branch description and git-merge will propose the branch description for\n>>> the merge commit.\n>>\n>> I almost suggested the same, but there is a problem with this\n>> approach: if you're are on a detached head, where does git-am save it?\n\nWhat would the user expect? We can have a range of expectations:\n1) reject and error out git-am\n2) warn about not saving branch.description and continue with am\n3) have a (maybe special) branch.HEAD.description thing, same for FETCH_HEAD etc\n4) have a config option to choose between 1 and 2, if unset default to 1\n\nI think 3 is a bad choice.\n4 seems reasonable to me, though I wonder if some people use git-am in\na scripted workflow with a detached head and then create the branch afterwards?\nSo\n\n5) create a branch for them? (such as $(date)-${subject})\n\nMy gut reaction doesn't like 5 either.\n\n>> --\n>> Duy\n>\n> Also, what about the case where a branch already has a description\n> such as is the case for something other than an integration branch.\n> How does git-am know the difference and ensure it doesn't overwrite\n> anything? Not everyone uses separate branches for each patch and such.\n\nI would imagine this is similar to the pull requests on the linux\nmailing list, i.e.\nhow it is with merges. Back in the time we did not open the editor for you to\ntalk about the merge you just did, and then we started doing that.\n\nSo what to do when the description already exists?\n\nWe could amend the description separated by a\n\n # comment, below was added:\n\nline or such and then open the editor asked for user input.\n\nThanks,\nStefan\n\n>\n> Thanks,\n> Jake\n"},{"id":"299318","messageId":"CA+P7+xpgzRGiNtWrzjebP4EJr1kCed4w5JX412FhSHoZZrkNRA@mail.gmail.com","threadId":"40318","inReplyTo":"CAGZ79kb27JZepMD5AmrHjOnf8haE8LehZd_CkvOQ1UoLEDuxKQ@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-15T06:38:57Z","receivedAt":"2016-08-15T06:39:23Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Sun, Aug 14, 2016 at 11:28 PM, Stefan Beller wrote:\n> I would imagine this is similar to the pull requests on the linux\n> mailing list, i.e.\n> how it is with merges. Back in the time we did not open the editor for you to\n> talk about the merge you just did, and then we started doing that.\n>\n> So what to do when the description already exists?\n>\n> We could amend the description separated by a\n>\n> # comment, below was added:\n>\n> line or such and then open the editor asked for user input.\n>\n> Thanks,\n> Stefan\n>\n\nThis is why my gut feeling is that we should instead have a separate\nway to store a cover letter, as it doesn't necessarily have to apply\nto a branch or a merge commit, but could just be annotation against a\nseries of commits (maybe stored as base + tip, since most series would\nbe linear in nature?)\n\nHowever, opening an editor and amending seems quite reasonable to me\nif we're just editing branch description, and then storing that as\npart of merge commit would be reasonable?\n\nI really think we want some alternative way to store it for other use\ncases besides the description, though.\n\nRegards,\nJake\n"},{"id":"299319","messageId":"CAGZ79kZG2H8P13ivDJWYM7snmw3EqrGr=FaaHkXJotzhRfa00A@mail.gmail.com","threadId":"40318","inReplyTo":"CA+P7+xpgzRGiNtWrzjebP4EJr1kCed4w5JX412FhSHoZZrkNRA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-15T06:49:47Z","receivedAt":"2016-08-15T06:49:53Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Sun, Aug 14, 2016 at 11:38 PM, Jacob Keller wrote:\n> On Sun, Aug 14, 2016 at 11:28 PM, Stefan Beller wrote:\n>> I would imagine this is similar to the pull requests on the linux\n>> mailing list, i.e.\n>> how it is with merges. Back in the time we did not open the editor for you to\n>> talk about the merge you just did, and then we started doing that.\n>>\n>> So what to do when the description already exists?\n>>\n>> We could amend the description separated by a\n>>\n>> # comment, below was added:\n>>\n>> line or such and then open the editor asked for user input.\n>>\n>> Thanks,\n>> Stefan\n>>\n>\n> This is why my gut feeling is that we should instead have a separate\n> way to store a cover letter, as it doesn't necessarily have to apply\n> to a branch\n\nWell in our workflow each series has at least one merge commit.\n(You *could* have different descriptions for the different branches,\ne.g. for maint: \"fixes a segfault so let's get this in, but it needs to be\nredone properly\" and for pu: \"TODO: revert this partially\nwhen branch $proper-fix is merged\")\n\n> or a merge commit, but could just be annotation against a\n> series of commits (maybe stored as base + tip, since most series would\n> be linear in nature?)\n\nWe could suggest to use a merge always strategy for this, i.e. as soon as\nyou send a cover-letter, we'll make a merge for you whose parents are the\nold HEAD and the new series?\n\nIf the user strictly wants to have a linear history, then we could try some\nempty commit magic before or after the series, but I doubt this is proper.\n\nIf users insist on linear history, they deny the benefits of a DAG that\nrepresents how the source code evolved. (Also see the eternal rebase\nvs merge discussion ;)\n\n>\n> However, opening an editor and amending seems quite reasonable to me\n> if we're just editing branch description, and then storing that as\n> part of merge commit would be reasonable?\n>\n> I really think we want some alternative way to store it for other use\n> cases besides the description, though.\n\n\"besides the description\"?\n\nWhat do you mean by that?\n\nThanks,\nStefan\n\n>\n> Regards,\n> Jake\n"},{"id":"299320","messageId":"CA+P7+xrSPW_=S6P=wGZB=3F_jRxatZoCP4F+GButeoBEMHjpRA@mail.gmail.com","threadId":"40318","inReplyTo":"CAGZ79kZG2H8P13ivDJWYM7snmw3EqrGr=FaaHkXJotzhRfa00A@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-15T06:52:35Z","receivedAt":"2016-08-15T06:53:01Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Sun, Aug 14, 2016 at 11:49 PM, Stefan Beller wrote:\n> On Sun, Aug 14, 2016 at 11:38 PM, Jacob Keller wrote:\n>> On Sun, Aug 14, 2016 at 11:28 PM, Stefan Beller wrote:\n>>> I would imagine this is similar to the pull requests on the linux\n>>> mailing list, i.e.\n>>> how it is with merges. Back in the time we did not open the editor for you to\n>>> talk about the merge you just did, and then we started doing that.\n>>>\n>>> So what to do when the description already exists?\n>>>\n>>> We could amend the description separated by a\n>>>\n>>> # comment, below was added:\n>>>\n>>> line or such and then open the editor asked for user input.\n>>>\n>>> Thanks,\n>>> Stefan\n>>>\n>>\n>> This is why my gut feeling is that we should instead have a separate\n>> way to store a cover letter, as it doesn't necessarily have to apply\n>> to a branch\n>\n> Well in our workflow each series has at least one merge commit.\n> (You *could* have different descriptions for the different branches,\n> e.g. for maint: \"fixes a segfault so let's get this in, but it needs to be\n> redone properly\" and for pu: \"TODO: revert this partially\n> when branch $proper-fix is merged\")\n>\n>> or a merge commit, but could just be annotation against a\n>> series of commits (maybe stored as base + tip, since most series would\n>> be linear in nature?)\n>\n> We could suggest to use a merge always strategy for this, i.e. as soon as\n> you send a cover-letter, we'll make a merge for you whose parents are the\n> old HEAD and the new series?\n>\n> If the user strictly wants to have a linear history, then we could try some\n> empty commit magic before or after the series, but I doubt this is proper.\n>\n> If users insist on linear history, they deny the benefits of a DAG that\n> represents how the source code evolved. (Also see the eternal rebase\n> vs merge discussion ;)\n>\n\nI think you're right this can go into a merge commit and if a user\ninsists on linear history it's their fault.\n\n>>\n>> However, opening an editor and amending seems quite reasonable to me\n>> if we're just editing branch description, and then storing that as\n>> part of merge commit would be reasonable?\n>>\n>> I really think we want some alternative way to store it for other use\n>> cases besides the description, though.\n>\n> \"besides the description\"?\n\nI think my brain shut down. I'm not really sure what I meant but I\nthink I meant \"we want some other way to make the cover letter\npermanent because the branch description isn't shared\".... So... no I\nhave no real idea what I was trying to say here.\n\nThanks,\nJake\n\n>\n> What do you mean by that?\n>\n> Thanks,\n> Stefan\n>\n>>\n>> Regards,\n>> Jake\n"},{"id":"299322","messageId":"CACsJy8BdmR5USJvjJ6xbjj=bP787tdS72_oL+PDq0D+FPYmiPA@mail.gmail.com","threadId":"40318","inReplyTo":"CAGZ79kb27JZepMD5AmrHjOnf8haE8LehZd_CkvOQ1UoLEDuxKQ@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-15T09:40:51Z","receivedAt":"2016-08-15T09:41:44Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Aug 15, 2016 at 1:28 PM, Stefan Beller wrote:\n> On Sun, Aug 14, 2016 at 12:15 AM, Jacob Keller wrote:\n>> On Sat, Aug 13, 2016 at 1:49 AM, Duy Nguyen wrote:\n>>> On Tue, Aug 9, 2016 at 12:27 AM, Stefan Beller wrote:\n>>>> is what you want. Maybe we want to see a patch that adds the reverse\n>>>> functionality as well, i.e. git-am will store the the cover letter as the\n>>>> branch description and git-merge will propose the branch description for\n>>>> the merge commit.\n>>>\n>>> I almost suggested the same, but there is a problem with this\n>>> approach: if you're are on a detached head, where does git-am save it?\n>\n> What would the user expect? We can have a range of expectations:\n> 1) reject and error out git-am\n> 2) warn about not saving branch.description and continue with am\n> 3) have a (maybe special) branch.HEAD.description thing, same for FETCH_HEAD etc\n> 4) have a config option to choose between 1 and 2, if unset default to 1\n>\n> I think 3 is a bad choice.\n> 4 seems reasonable to me, though I wonder if some people use git-am in\n> a scripted workflow with a detached head and then create the branch afterwards?\n> So\n>\n> 5) create a branch for them? (such as $(date)-${subject})\n>\n> My gut reaction doesn't like 5 either.\n\nI'm starting to think option 6 (storing cover latter as an empty\ncommit at tip then git-merge replaces it with a merge commit in a\npermanent history) may be the way to go. It handles detached heads\njust fine, we have reflog to store older cover letters. Though it will\nnot play nice with 'git commit --amend' and 'git reset' for people who\nrewrites history heavily during development, but maybe 'git rebase -i\n--autosquash' would be an ok workflow alternative.\n-- \nDuy\n"},{"id":"299336","messageId":"DD86BC6E2E3245BA991E4D65CE66E4A8@PhilipOakley","threadId":"40318","inReplyTo":"CACsJy8BdmR5USJvjJ6xbjj=bP787tdS72_oL+PDq0D+FPYmiPA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-15T12:37:33Z","receivedAt":"2016-08-15T12:38:58Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Duy Nguyen\" \n> On Mon, Aug 15, 2016 at 1:28 PM, Stefan Beller wrote:\n>> On Sun, Aug 14, 2016 at 12:15 AM, Jacob Keller \n>> wrote:\n>>> On Sat, Aug 13, 2016 at 1:49 AM, Duy Nguyen wrote:\n>>>> On Tue, Aug 9, 2016 at 12:27 AM, Stefan Beller \n>>>> wrote:\n>>>>> is what you want. Maybe we want to see a patch that adds the reverse\n>>>>> functionality as well, i.e. git-am will store the the cover letter as\n>>>>> the\n>>>>> branch description and git-merge will propose the branch description\n>>>>> for\n>>>>> the merge commit.\n>>>>\n>>>> I almost suggested the same, but there is a problem with this\n>>>> approach: if you're are on a detached head, where does git-am save it?\n>>\n>> What would the user expect? We can have a range of expectations:\n>> 1) reject and error out git-am\n>> 2) warn about not saving branch.description and continue with am\n>> 3) have a (maybe special) branch.HEAD.description thing, same for\n>> FETCH_HEAD etc\n>> 4) have a config option to choose between 1 and 2, if unset default to 1\n>>\n>> I think 3 is a bad choice.\n>> 4 seems reasonable to me, though I wonder if some people use git-am in\n>> a scripted workflow with a detached head and then create the branch\n>> afterwards?\n>> So\n>>\n>> 5) create a branch for them? (such as $(date)-${subject})\n>>\n>> My gut reaction doesn't like 5 either.\n>\n> I'm starting to think option 6 (storing cover latter as an empty\n> commit at tip then git-merge replaces it with a merge commit in a\n> permanent history) may be the way to go. It handles detached heads\n> just fine, we have reflog to store older cover letters. Though it will\n> not play nice with 'git commit --amend' and 'git reset' for people who\n> rewrites history heavily during development, but maybe 'git rebase -i\n> --autosquash' would be an ok workflow alternative.\n> -- \n\n[sorry if this is not the right place to 'drop in'..]\nI appreciate there has been a lot of discussion, but it mainly appears to be\nabout an upstream / integration viewpoint.\n\nI'd hate it if there was a one size fits all solution that was only focused\non one important use case, rather than having at least a simple fallback for\nsimple folk.\n\nPersonally I liked the idea that I could start my patch series branch with a\nsimple 'empty' commit with a commit message that read \"cover! \" and continue with the cover letter. It's essentially the same\nas the fixup! and squash! idea (more the latter - it's squash! without a\npredecessor). For moderate size series a simple 'git rebase master..' is\nsufficient to see the whole series and decide which need editing, rewording,\nswapping, checking the fixups, etc.\n\nFormat-patch would then be taught to spot that the first commit in the\nseries is \"cover! \" and create the usual 0/N cover letter. Git Gui\nmay need to be taught to recognise cover! (haven't checked if it recognises\nan empty commit squash!). Possibly 'git commit' may want a --cover option to\nmassage the commit message and add --allow-empty, but that's finesse.\n\nI've no problem with more extensive methods for those preparing very big\npatch series, or with those needing to merge together a lot of series and\nwant to keep the cover letters, but ensuring that a simple flow is possible\nshould still be there.\n--\nPhilip\n\n"},{"id":"299342","messageId":"CACsJy8DWDEQOKLV+c1zCXhiHZbxF3iM9_rFWhju3hk=Ji1i3ZQ@mail.gmail.com","threadId":"40318","inReplyTo":"DD86BC6E2E3245BA991E4D65CE66E4A8@PhilipOakley","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-15T13:30:03Z","receivedAt":"2016-08-15T13:30:39Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Aug 15, 2016 at 7:37 PM, Philip Oakley wrote:\n> I appreciate there has been a lot of discussion, but it mainly appears to be\n> about an upstream / integration viewpoint.\n>\n> I'd hate it if there was a one size fits all solution that was only focused\n> on one important use case, rather than having at least a simple fallback for\n> simple folk.\n>\n> Personally I liked the idea that I could start my patch series branch with a\n> simple 'empty' commit with a commit message that read \"cover! the series>\" and continue with the cover letter. It's essentially the same\n> as the fixup! and squash! idea (more the latter - it's squash! without a\n> predecessor). For moderate size series a simple 'git rebase master..' is\n> sufficient to see the whole series and decide which need editing, rewording,\n> swapping, checking the fixups, etc.\n\nI think you hit the jackpot (or are getting very close). This removes\nthe special status of \"the commit at the tip of the branch\" cover\nletter. Maybe I just like it so much I have a hard time finding\nanything wrong with it :)\n\n> Format-patch would then be taught to spot that the first commit in the\n> series is \"cover! \" and create the usual 0/N cover letter. Git Gui\n> may need to be taught to recognise cover! (haven't checked if it recognises\n> an empty commit squash!). Possibly 'git commit' may want a --cover option to\n> massage the commit message and add --allow-empty, but that's finesse.\n>\n> I've no problem with more extensive methods for those preparing very big\n> patch series, or with those needing to merge together a lot of series and\n> want to keep the cover letters, but ensuring that a simple flow is possible\n> should still be there.\n-- \nDuy\n"},{"id":"299343","messageId":"20160815134728.atwmswrlxtwzpaxl@john.keeping.me.uk","threadId":"40318","inReplyTo":"CACsJy8DWDEQOKLV+c1zCXhiHZbxF3iM9_rFWhju3hk=Ji1i3ZQ@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2016-08-15T13:47:28Z","receivedAt":"2016-08-15T13:47:59Z","isPatch":false,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Mon, Aug 15, 2016 at 08:30:03PM +0700, Duy Nguyen wrote:\n> On Mon, Aug 15, 2016 at 7:37 PM, Philip Oakley wrote:\n> > I appreciate there has been a lot of discussion, but it mainly appears to be\n> > about an upstream / integration viewpoint.\n> >\n> > I'd hate it if there was a one size fits all solution that was only focused\n> > on one important use case, rather than having at least a simple fallback for\n> > simple folk.\n> >\n> > Personally I liked the idea that I could start my patch series branch with a\n> > simple 'empty' commit with a commit message that read \"cover! > the series>\" and continue with the cover letter. It's essentially the same\n> > as the fixup! and squash! idea (more the latter - it's squash! without a\n> > predecessor). For moderate size series a simple 'git rebase master..' is\n> > sufficient to see the whole series and decide which need editing, rewording,\n> > swapping, checking the fixups, etc.\n> \n> I think you hit the jackpot (or are getting very close). This removes\n> the special status of \"the commit at the tip of the branch\" cover\n> letter. Maybe I just like it so much I have a hard time finding\n> anything wrong with it :)\n\nI haven't followed this thread too closely, but has anyone mentioned\nU-Boot's patman tool[1] yet?\n\nIt defines several special trailers that can be used to annotate commits\nwith additional information to use when mailing them and which are\nautomatically removed from the commit message in patches sent using\npatman.\n\n\n[1] http://git.denx.de/?p=u-boot.git;a=blob;f=tools/patman/README\n"},{"id":"299385","messageId":"CA+P7+xqbmZznxq024fhkejp2FeCVYkOYHTSdR69Di3nkzYJooA@mail.gmail.com","threadId":"40318","inReplyTo":"DD86BC6E2E3245BA991E4D65CE66E4A8@PhilipOakley","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-15T20:09:42Z","receivedAt":"2016-08-15T20:10:09Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Mon, Aug 15, 2016 at 5:37 AM, Philip Oakley wrote:\n> [sorry if this is not the right place to 'drop in'..]\n> I appreciate there has been a lot of discussion, but it mainly appears to be\n> about an upstream / integration viewpoint.\n>\n> I'd hate it if there was a one size fits all solution that was only focused\n> on one important use case, rather than having at least a simple fallback for\n> simple folk.\n>\n> Personally I liked the idea that I could start my patch series branch with a\n> simple 'empty' commit with a commit message that read \"cover! the series>\" and continue with the cover letter. It's essentially the same\n> as the fixup! and squash! idea (more the latter - it's squash! without a\n> predecessor). For moderate size series a simple 'git rebase master..' is\n> sufficient to see the whole series and decide which need editing, rewording,\n> swapping, checking the fixups, etc.\n>\n> Format-patch would then be taught to spot that the first commit in the\n> series is \"cover! \" and create the usual 0/N cover letter. Git Gui\n> may need to be taught to recognise cover! (haven't checked if it recognises\n> an empty commit squash!). Possibly 'git commit' may want a --cover option to\n> massage the commit message and add --allow-empty, but that's finesse.\n>\n> I've no problem with more extensive methods for those preparing very big\n> patch series, or with those needing to merge together a lot of series and\n> want to keep the cover letters, but ensuring that a simple flow is possible\n> should still be there.\n> --\n> Philip\n>\n\nSome people have suggested this simple idea, and I like it, but they\ndid mention that modifying the cover letter now requires a rebase over\na potentially large series of patches, which can get annoying.\n\nThanks,\nJake\n"},{"id":"299393","messageId":"xmqqwpjhg42v.fsf@gitster.mtv.corp.google.com","threadId":"40318","inReplyTo":"CA+P7+xqbmZznxq024fhkejp2FeCVYkOYHTSdR69Di3nkzYJooA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-15T20:38:48Z","receivedAt":"2016-08-15T20:38:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jacob Keller writes:\n\n> Some people have suggested this simple idea, and I like it, but they\n> did mention that modifying the cover letter now requires a rebase over\n> a potentially large series of patches, which can get annoying.\n\nThat can be simply solved by keeping the cover at the end. When you\nare updating the real patch on the series with \"rebase -i\", you\nwould have a chance to update the cover at the same time that way.\n\n"},{"id":"299396","messageId":"3E80981D72F74A11A41A228901644E1C@PhilipOakley","threadId":"40318","inReplyTo":"CA+P7+xqbmZznxq024fhkejp2FeCVYkOYHTSdR69Di3nkzYJooA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-15T20:46:16Z","receivedAt":"2016-08-15T20:46:21Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jacob Keller\" \n[nip]\n>>\n>> I've no problem with more extensive methods for those preparing very big\n>> patch series, or with those needing to merge together a lot of series and\n>> want to keep the cover letters, but ensuring that a simple flow is \n>> possible\n>> should still be there.\n>> --\n>> Philip\n>>\n>\n> Some people have suggested this simple idea, and I like it, but they\n> did mention that modifying the cover letter now requires a rebase over\n> a potentially large series of patches, which can get annoying.\n>\n> Thanks,\n> Jake\n\nThey can just add \"squash! cover! \" commits for that ;-) Though more \nlikely the advanced workflow would be used... We'll need both (more than \none) options.\n--\nPhilip \n\n"},{"id":"299420","messageId":"CA+P7+xpVOMH6qa6j+oCizcWvO30t1zYA1MD3jkw-7yzw6SPy2w@mail.gmail.com","threadId":"40318","inReplyTo":"xmqqwpjhg42v.fsf@gitster.mtv.corp.google.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-15T23:01:05Z","receivedAt":"2016-08-15T23:01:31Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Mon, Aug 15, 2016 at 1:38 PM, Junio C Hamano wrote:\n> Jacob Keller writes:\n>\n>> Some people have suggested this simple idea, and I like it, but they\n>> did mention that modifying the cover letter now requires a rebase over\n>> a potentially large series of patches, which can get annoying.\n>\n> That can be simply solved by keeping the cover at the end. When you\n> are updating the real patch on the series with \"rebase -i\", you\n> would have a chance to update the cover at the same time that way.\n>\n\nIt has problems keeping it at the end as well because that makes\nregular commits and commit --amend funky.., but you could do squashes\ninto the cover letter easily enough as suggested by Philip Oakley. I\nthink that might be the most natural flow we have now that doesn't\ndepend on creating some fancy new object type.\n\nThanks,\nJake\n"},{"id":"299428","messageId":"CACsJy8CXKcjo6KO8HvBpx+N4Lj7MO5yMH2q4bVWi-x3mbvWsmQ@mail.gmail.com","threadId":"40318","inReplyTo":"3E80981D72F74A11A41A228901644E1C@PhilipOakley","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-16T03:45:04Z","receivedAt":"2016-08-16T03:45:40Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Aug 16, 2016 at 3:46 AM, Philip Oakley wrote:\n> From: \"Jacob Keller\" \n> [nip]\n>>>\n>>>\n>>> I've no problem with more extensive methods for those preparing very big\n>>> patch series, or with those needing to merge together a lot of series and\n>>> want to keep the cover letters, but ensuring that a simple flow is\n>>> possible\n>>> should still be there.\n>>> --\n>>> Philip\n>>>\n>>\n>> Some people have suggested this simple idea, and I like it, but they\n>> did mention that modifying the cover letter now requires a rebase over\n>> a potentially large series of patches, which can get annoying.\n>>\n>> Thanks,\n>> Jake\n>\n>\n> They can just add \"squash! cover! \" commits for that ;-) Though more\n> likely the advanced workflow would be used... We'll need both (more than\n> one) options.\n\nOr even better, \"git commit --reword $SHA1\" brings up the editor with\ncommit message of $SHA1. Modify any way you want and it creates a new\nempty, \"reword!\" commit that contains the diff between the old commit\nmessage and the new one. \"reword!\" can be consumed by \"rebase -i\n--autosquash\" without bringing up the editor again. I realize making\n\"git commit --reword\" run multiple times would be tricky though...\n-- \nDuy\n"},{"id":"299430","messageId":"CA+P7+xr+HonJTj5AcRhAMf5Z059zHKiuOY8Zbd77uu_jAiiZBA@mail.gmail.com","threadId":"40318","inReplyTo":"CACsJy8CXKcjo6KO8HvBpx+N4Lj7MO5yMH2q4bVWi-x3mbvWsmQ@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-16T05:26:35Z","receivedAt":"2016-08-16T05:27:12Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Mon, Aug 15, 2016 at 8:45 PM, Duy Nguyen wrote:\n> On Tue, Aug 16, 2016 at 3:46 AM, Philip Oakley wrote:\n>> From: \"Jacob Keller\" \n>> [nip]\n>>>>\n>>>>\n>>>> I've no problem with more extensive methods for those preparing very big\n>>>> patch series, or with those needing to merge together a lot of series and\n>>>> want to keep the cover letters, but ensuring that a simple flow is\n>>>> possible\n>>>> should still be there.\n>>>> --\n>>>> Philip\n>>>>\n>>>\n>>> Some people have suggested this simple idea, and I like it, but they\n>>> did mention that modifying the cover letter now requires a rebase over\n>>> a potentially large series of patches, which can get annoying.\n>>>\n>>> Thanks,\n>>> Jake\n>>\n>>\n>> They can just add \"squash! cover! \" commits for that ;-) Though more\n>> likely the advanced workflow would be used... We'll need both (more than\n>> one) options.\n>\n> Or even better, \"git commit --reword $SHA1\" brings up the editor with\n> commit message of $SHA1. Modify any way you want and it creates a new\n> empty, \"reword!\" commit that contains the diff between the old commit\n> message and the new one. \"reword!\" can be consumed by \"rebase -i\n> --autosquash\" without bringing up the editor again. I realize making\n> \"git commit --reword\" run multiple times would be tricky though...\n> --\n> Duy\n\nI was just thinking you write text and it gets appended to the text of\nthe reworded commit, and when you squash them using rebase you get to\nfinalize it like a normal squash?\n\nThanks,\nJake\n"},{"id":"299431","messageId":"CACsJy8DJmONcgQO37Xk+2cZb+Svx-bgwjrG1XrZQ4BYipownqw@mail.gmail.com","threadId":"40318","inReplyTo":"CA+P7+xr+HonJTj5AcRhAMf5Z059zHKiuOY8Zbd77uu_jAiiZBA@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2016-08-16T06:45:05Z","receivedAt":"2016-08-16T06:45:40Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Aug 16, 2016 at 12:26 PM, Jacob Keller wrote:\n>>> They can just add \"squash! cover! \" commits for that ;-) Though more\n>>> likely the advanced workflow would be used... We'll need both (more than\n>>> one) options.\n>>\n>> Or even better, \"git commit --reword $SHA1\" brings up the editor with\n>> commit message of $SHA1. Modify any way you want and it creates a new\n>> empty, \"reword!\" commit that contains the diff between the old commit\n>> message and the new one. \"reword!\" can be consumed by \"rebase -i\n>> --autosquash\" without bringing up the editor again. I realize making\n>> \"git commit --reword\" run multiple times would be tricky though...\n>\n> I was just thinking you write text and it gets appended to the text of\n> the reworded commit, and when you squash them using rebase you get to\n> finalize it like a normal squash?\n\nI think that's what Phillip meant by 'squash! cover!' though I wanted\nto go further, I don't want an editor popping up at rebase time,\ninstead 'rebase' just update cover letter automatically for me.\n-- \nDuy\n"},{"id":"299467","messageId":"CA+P7+xqDMgi8pvAN-Pme7SE=C=m3xq6o2aQxnyxzPJEbyiqMhA@mail.gmail.com","threadId":"40318","inReplyTo":"CACsJy8DJmONcgQO37Xk+2cZb+Svx-bgwjrG1XrZQ4BYipownqw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2016-08-16T15:52:46Z","receivedAt":"2016-08-16T15:53:18Z","isPatch":false,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Mon, Aug 15, 2016 at 11:45 PM, Duy Nguyen wrote:\n> On Tue, Aug 16, 2016 at 12:26 PM, Jacob Keller wrote:\n>>>> They can just add \"squash! cover! \" commits for that ;-) Though more\n>>>> likely the advanced workflow would be used... We'll need both (more than\n>>>> one) options.\n>>>\n>>> Or even better, \"git commit --reword $SHA1\" brings up the editor with\n>>> commit message of $SHA1. Modify any way you want and it creates a new\n>>> empty, \"reword!\" commit that contains the diff between the old commit\n>>> message and the new one. \"reword!\" can be consumed by \"rebase -i\n>>> --autosquash\" without bringing up the editor again. I realize making\n>>> \"git commit --reword\" run multiple times would be tricky though...\n>>\n>> I was just thinking you write text and it gets appended to the text of\n>> the reworded commit, and when you squash them using rebase you get to\n>> finalize it like a normal squash?\n>\n> I think that's what Phillip meant by 'squash! cover!' though I wanted\n> to go further, I don't want an editor popping up at rebase time,\n> instead 'rebase' just update cover letter automatically for me.\n> --\n> Duy\n\nMaybe teach it some sort of \"reword! cover!\" which pops up an editor\nand you can edit to your hearts content, and it just saves the \"new\"\nmessage. Since there is no such thing as a diff on message contents,\nit would just be a complete replace for the new message (obviously we\nwould then strip reword and cover part out but otherwise leave the\nrest in place so rebase machinery would be able to fix it up without\nyou having to edit it a second time in the rebase process? That\ndoesn't seem as complicated as somehow storing a new diff format for\nthe cover letter. Not sure how to handle several in a row though.\n\nThanks,\nJake\n"},{"id":"299518","messageId":"A12D8350E1E24F12B530B6EBC9B4E321@PhilipOakley","threadId":"40318","inReplyTo":"CACsJy8DJmONcgQO37Xk+2cZb+Svx-bgwjrG1XrZQ4BYipownqw@mail.gmail.com","subject":"Re: storing cover letter of a patch series?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-16T21:29:33Z","receivedAt":"2016-08-16T21:29:40Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Duy Nguyen\" \n> On Tue, Aug 16, 2016 at 12:26 PM, Jacob Keller \n> wrote:\n>>>> They can just add \"squash! cover! \" commits for that ;-) Though \n>>>> more\n>>>> likely the advanced workflow would be used... We'll need both (more \n>>>> than\n>>>> one) options.\n>>>\n>>> Or even better, \"git commit --reword $SHA1\" brings up the editor with\n>>> commit message of $SHA1. Modify any way you want and it creates a new\n>>> empty, \"reword!\" commit that contains the diff between the old commit\n>>> message and the new one. \"reword!\" can be consumed by \"rebase -i\n>>> --autosquash\" without bringing up the editor again. I realize making\n>>> \"git commit --reword\" run multiple times would be tricky though...\n>>\n>> I was just thinking you write text and it gets appended to the text of\n>> the reworded commit, and when you squash them using rebase you get to\n>> finalize it like a normal squash?\n>\n> I think that's what Phillip meant by 'squash! cover!' though I wanted\n> to go further, I don't want an editor popping up at rebase time,\n> instead 'rebase' just update cover letter automatically for me.\n> -- \nHi Duy,\nWhile we can have code that is auto merged, I don't think that I'd want to \nsubmit a cover letter that was simply auto merged. I'd want to refresh and \nre-personalise the text. As long as the flexibility in our cover letter \ninclusion is there....\n--\nPhilip\n\n"}]}