{"thread":{"id":"60417","subject":"[RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","startedAt":"2023-10-23T13:00:20Z","lastAt":"2023-10-31T18:48:24Z","messageCount":17,"participants":["Oswald Buddenhagen","Phillip Wood","Taylor Blau","Marc Branchaud","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"483667","messageId":"20231023130016.1093356-1-oswald.buddenhagen@gmx.de","threadId":"60417","inReplyTo":null,"subject":"[RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-23T13:00:16Z","receivedAt":"2023-10-23T13:00:20Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"Create a clear top-down structure which makes it hopefully unambiguous\nwhat happens when.\n\nAlso mention the timestamp along with the author - this is primarily\nmeant to include the keywords somebody might be searching for, like I\ndid a year ago.\n\nSigned-off-by: Oswald Buddenhagen \n\n---\nv2:\n- slight adjustments inspired by marc. however, i left most things\n unchanged or even went in the opposite direction, because i assume the\n readers to be sufficiently context-sensitive, and the objective is\n merely to be not actively confusing. adding redundancy in the name of\n clarity would just make the text stylistically inferior and arguably\n harder to read.\n\nCc: Junio C Hamano \nCc: Phillip Wood \nCc: Christian Couder \nCc: Charvi Mendiratta \nCc: Marc Branchaud \n---\n Documentation/git-rebase.txt | 29 +++++++++++++++--------------\n 1 file changed, 15 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex e7b39ad244..337df9ef2f 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -890,20 +890,21 @@ command \"pick\" with the command \"reword\".\n To drop a commit, replace the command \"pick\" with \"drop\", or just\n delete the matching line.\n \n-If you want to fold two or more commits into one, replace the command\n-\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n-If the commits had different authors, the folded commit will be\n-attributed to the author of the first commit. The suggested commit\n-message for the folded commit is the concatenation of the first\n-commit's message with those identified by \"squash\" commands, omitting the\n-messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n-is used. In that case the suggested commit message is only the message\n-of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n-the message. The contents (patch) of the \"fixup -c\" commit are still\n-incorporated into the folded commit. If there is more than one \"fixup -c\"\n-commit, the message from the final one is used. You can also use\n-\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n-an editor.\n+If you want to fold two or more commits into one (that is, to combine\n+their contents/patches), replace the command \"pick\" for the second and\n+subsequent commits with \"squash\" or \"fixup\".\n+The commit message for the folded commit is the concatenation of the\n+message of the first commit with those of commits identified by \"squash\"\n+commands, omitting those of commits identified by \"fixup\" commands,\n+unless \"fixup -c\" is used. In the latter case, the message is obtained\n+only from the \"fixup -c\" commit (having more than one of these is\n+incorrect).\n+If the resulting commit message is a concatenation of multiple messages,\n+an editor is opened allowing you to edit it. This is also the case for a\n+message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n+the editor; this is analogous to the behavior of `git commit`.\n+The first commit which contributes to the suggested commit message also\n+determines the author, along with the date/timestamp.\n \n `git rebase` will stop when \"pick\" has been replaced with \"edit\" or\n when a command fails due to merge errors. When you are done editing\n-- \n2.42.0.419.g70bf8a5751\n\n"},{"id":"483682","messageId":"a85c80eb-65ab-4b8c-ba94-de71516da5ef@gmail.com","threadId":"60417","inReplyTo":"20231023130016.1093356-1-oswald.buddenhagen@gmx.de","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-10-23T16:01:02Z","receivedAt":"2023-10-23T16:01:08Z","isPatch":false,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Oswald\n\nOn 23/10/2023 14:00, Oswald Buddenhagen wrote:\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index e7b39ad244..337df9ef2f 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -890,20 +890,21 @@ command \"pick\" with the command \"reword\".\n> To drop a commit, replace the command \"pick\" with \"drop\", or just\n> delete the matching line.\n> \n> -If you want to fold two or more commits into one, replace the command\n> -\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n> -If the commits had different authors, the folded commit will be\n> -attributed to the author of the first commit. The suggested commit\n> -message for the folded commit is the concatenation of the first\n> -commit's message with those identified by \"squash\" commands, omitting the\n> -messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n> -is used. In that case the suggested commit message is only the message\n> -of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n> -the message. The contents (patch) of the \"fixup -c\" commit are still\n> -incorporated into the folded commit. If there is more than one \"fixup -c\"\n> -commit, the message from the final one is used. You can also use\n> -\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n> -an editor.\n> +If you want to fold two or more commits into one (that is, to combine\n> +their contents/patches), replace the command \"pick\" for the second and\n> +subsequent commits with \"squash\" or \"fixup\".\n> +The commit message for the folded commit is the concatenation of the\n> +message of the first commit with those of commits identified by \"squash\"\n> +commands, omitting those of commits identified by \"fixup\" commands,\n> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n> +only from the \"fixup -c\" commit (having more than one of these is\n> +incorrect).\n\nThis change is incorrect - it is perfectly fine to have more than one \n\"fixup -c\" command. In that case we use the message of the commit of the \nfinal \"fixup -c\" command. One case where there can be multiple \"fixup \n-c\" commands is when a commit has been reworded several times via \"git \ncommit --fixup=reword:\" and the user runs \"git rebase --autosquash\"\n\n> +If the resulting commit message is a concatenation of multiple messages,\n> +an editor is opened allowing you to edit it. This is also the case for a\n> +message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n> +the editor; this is analogous to the behavior of `git commit`.\n> +The first commit which contributes to the suggested commit message also\n> +determines the author, along with the date/timestamp.\n\nIn the case of\n\npick A\nfixup -C B\n\ndon't we keep the authorship from A and just use the commit message from B?\n\nBest Wishes\n\nPhillip\n\n"},{"id":"483686","messageId":"ZTamhY1sTpp1N6n+@nand.local","threadId":"60417","inReplyTo":"20231023130016.1093356-1-oswald.buddenhagen@gmx.de","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2023-10-23T16:59:49Z","receivedAt":"2023-10-23T16:59:57Z","isPatch":false,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, Oct 23, 2023 at 03:00:16PM +0200, Oswald Buddenhagen wrote:\n> ---\n> Documentation/git-rebase.txt | 29 +++++++++++++++--------------\n> 1 file changed, 15 insertions(+), 14 deletions(-)\n\nThe new documentation below looks fine, and I don't have strong\nfeelings beyond the proposed modifications.\n\nThe line wrapping is a little odd: it looks like each sentence begins on\na its own line. Did you mean for there to be a visual separation between\nthose sentences in the rendered doc? If so, replace the single line feed\nwith a pair of them.\n\nIf not, this looks good to me as-is.\n\nThanks,\nTaylor\n"},{"id":"483691","messageId":"ZTayxB0Nm7AEyafp@ugly","threadId":"60417","inReplyTo":"a85c80eb-65ab-4b8c-ba94-de71516da5ef@gmail.com","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-23T17:52:04Z","receivedAt":"2023-10-23T17:52:17Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Mon, Oct 23, 2023 at 05:01:02PM +0100, Phillip Wood wrote:\n>On 23/10/2023 14:00, Oswald Buddenhagen wrote:\n>> +unless \"fixup -c\" is used. In the latter case, the message is \n>> obtained\n>> +only from the \"fixup -c\" commit (having more than one of these is\n>> +incorrect).\n>\n>This change is incorrect - it is perfectly fine to have more than one \n>\"fixup -c\" command. In that case we use the message of the commit of the \n>final \"fixup -c\" command.\n>\ni know that this is the case, see the previous thread (which i failed to \nlink by header, cf. \nhttps://lore.kernel.org/all/20231020092707.917514-1-oswald.buddenhagen@gmx.de/T/#u \n).\n\n>One case where there can be multiple \"fixup -c\" commands is when a \n>commit has been reworded several times via \"git commit \n>--fixup=reword:\" and the user runs \"git rebase --autosquash\"\n>\na cleaner solution would be recognizing the situation and not generating \nthese contradicting commands in the first place. of course that would be \nmore complexity, but it would also allow catching accidental use.\n\nof course i can go back to documenting the status quo, but it seems kind \nof wrong.\n\n>In the case of\n>\n>pick A\n>fixup -C B\n>\n>don't we keep the authorship from A and just use the commit message from B?\n>\nuhm. we clearly do. that means i was given incorrect advice in \nhttps://lore.kernel.org/all/YjXRM5HiRizZ035p@ugly/T/#u (and so the \nthread is still looking for a resolution) ...\n\nregards\n"},{"id":"483760","messageId":"b2b76344-11b7-4f21-8658-f18ffcca2dea@gmail.com","threadId":"60417","inReplyTo":"ZTayxB0Nm7AEyafp@ugly","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-10-24T09:22:17Z","receivedAt":"2023-10-24T09:22:21Z","isPatch":false,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Oswald\n\nOn 23/10/2023 18:52, Oswald Buddenhagen wrote:\n> On Mon, Oct 23, 2023 at 05:01:02PM +0100, Phillip Wood wrote:\n>> On 23/10/2023 14:00, Oswald Buddenhagen wrote:\n>>> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n>>> +only from the \"fixup -c\" commit (having more than one of these is\n>>> +incorrect).\n>>\n>> This change is incorrect - it is perfectly fine to have more than one \n>> \"fixup -c\" command. In that case we use the message of the commit of \n>> the final \"fixup -c\" command.\n>>\n> i know that this is the case, see the previous thread (which i failed to \n> link by header, cf. \n> https://lore.kernel.org/all/20231020092707.917514-1-oswald.buddenhagen@gmx.de/T/#u ).\n\nAh, I see Marc has already raised this point.\n\n>> One case where there can be multiple \"fixup -c\" commands is  when a \n>> commit has been reworded several times via \"git commit \n>> --fixup=reword:\" and the user runs \"git rebase --autosquash\"\n>>\n> a cleaner solution would be recognizing the situation and not generating \n> these contradicting commands in the first place. of course that would be \n> more complexity, but it would also allow catching accidental use.\n> \n> of course i can go back to documenting the status quo, but it seems kind \n> of wrong.\n\nI agree there is an argument for improving the implementation of \n--autosquash but until we do I think it is counterproductive to change \nthe documentation like this as it will cause users to wonder why \"rebase \n--autosquash\" generates a todo list that is incorrect according to the \ndocumentation.\n\n>> In the case of\n>>\n>> pick A\n>> fixup -C B\n>>\n>> don't we keep the authorship from A and just use the commit message \n>> from B?\n>>\n> uhm. we clearly do. that means i was given incorrect advice in \n> https://lore.kernel.org/all/YjXRM5HiRizZ035p@ugly/T/#u (and so the \n> thread is still looking for a resolution) ...\n\nI'll take a look at that thread and comment there.\n\nI do think it is a good idea to document where the authorship of a \nrebased commit comes from.\n\nBest Wishes\n\nPhillip\n"},{"id":"483785","messageId":"e33f919d-1b6a-4944-ab5d-93ad0d323b68@xiplink.com","threadId":"60417","inReplyTo":"20231023130016.1093356-1-oswald.buddenhagen@gmx.de","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-24T14:01:07Z","receivedAt":"2023-10-24T14:01:14Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-23 09:00, Oswald Buddenhagen wrote:\n> Create a clear top-down structure which makes it hopefully unambiguous\n> what happens when.\n> \n> Also mention the timestamp along with the author - this is primarily\n> meant to include the keywords somebody might be searching for, like I\n> did a year ago.\n> \n> Signed-off-by: Oswald Buddenhagen \n> \n> ---\n> v2:\n> - slight adjustments inspired by marc. however, i left most things\n> unchanged or even went in the opposite direction, because i assume the\n> readers to be sufficiently context-sensitive, and the objective is\n> merely to be not actively confusing. adding redundancy in the name of\n> clarity would just make the text stylistically inferior and arguably\n> harder to read.\n\nI disagree with this on many levels, but your tone seems to brook no \ndiscussion and I do not want to get into a protracted debate here.\n\nI will only say that, I personally don't read man pages from \nstart-to-end like a novel. I jump to the part that explains the thing I \nneed to learn about. So I think your assumptions about what context a \nreader might have in mind when they see this text are invalid.\n\nSince we have very different notions about who is reading this, I think \nwe'll never agree on the final wording. I'll continue to make my \nsuggestions, but I won't stand in the way of these changes if I'm the \nonly one who thinks they could be better.\n\n> Cc: Junio C Hamano \n> Cc: Phillip Wood \n> Cc: Christian Couder \n> Cc: Charvi Mendiratta \n> Cc: Marc Branchaud \n> ---\n> Documentation/git-rebase.txt | 29 +++++++++++++++--------------\n> 1 file changed, 15 insertions(+), 14 deletions(-)\n> \n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index e7b39ad244..337df9ef2f 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -890,20 +890,21 @@ command \"pick\" with the command \"reword\".\n> To drop a commit, replace the command \"pick\" with \"drop\", or just\n> delete the matching line.\n> \n> -If you want to fold two or more commits into one, replace the command\n> -\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n> -If the commits had different authors, the folded commit will be\n> -attributed to the author of the first commit. The suggested commit\n> -message for the folded commit is the concatenation of the first\n> -commit's message with those identified by \"squash\" commands, omitting the\n> -messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n> -is used. In that case the suggested commit message is only the message\n> -of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n> -the message. The contents (patch) of the \"fixup -c\" commit are still\n> -incorporated into the folded commit. If there is more than one \"fixup -c\"\n> -commit, the message from the final one is used. You can also use\n> -\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n> -an editor.\n> +If you want to fold two or more commits into one (that is, to combine\n> +their contents/patches), replace the command \"pick\" for the second and\n> +subsequent commits with \"squash\" or \"fixup\".\n\ns/the command \"pick\"/the \"pick\" command/\n\n> +The commit message for the folded commit is the concatenation of the\n> +message of the first commit with those of commits identified by \"squash\"\n\ns/message of the first commit/picked commit's message/\n\n> +commands, omitting those of commits identified by \"fixup\" commands,\n> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n> +only from the \"fixup -c\" commit (having more than one of these is\n> +incorrect).\n\nAs Phillip said, this is wrong. I agree with Phillip that the \ndocumentation should reflect the actual implementation, not what we hope \nthe implementation might be some day.\n\n> +If the resulting commit message is a concatenation of multiple messages,\n> +an editor is opened allowing you to edit it. This is also the case for a\n> +message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n> +the editor; this is analogous to the behavior of `git commit`.\n> +The first commit which contributes to the suggested commit message also\n\ns/suggested/folded/ -- with \"fixup -C\" there is no \"suggested\" message.\n\n\nThanks,\n\n\t\tM.\n"},{"id":"483798","messageId":"xmqq34y0546g.fsf@gitster.g","threadId":"60417","inReplyTo":"b2b76344-11b7-4f21-8658-f18ffcca2dea@gmail.com","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-24T17:19:19Z","receivedAt":"2023-10-24T17:19:27Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n> I agree there is an argument for improving the implementation of\n> --autosquash but until we do I think it is counterproductive to change\n> the documentation like this as it will cause users to wonder why\n> \"rebase --autosquash\" generates a todo list that is incorrect\n> according to the documentation.\n\nThat's a good point.\n\n> I do think it is a good idea to document where the authorship of a\n> rebased commit comes from.\n\nYeah, sounds like a good idea. As to the authorship information, it\nmight be nicer if the \"rebase -i\" insn language supported an option\nto trigger --reset-author (or even better, --author=...) action for\na single commit, but I presume that it is rather a rare event, and\nas long as people understand that they can stop the sequencing\n(e.g., an \"edit\" of the commit would do) and run \"commit --amend\",\nit should be OK, so it probably is OK to leave it as-is.\n\nThanks.\n\n"},{"id":"483820","messageId":"ZTg0zXkvSQ6L+4Oj@ugly","threadId":"60417","inReplyTo":"e33f919d-1b6a-4944-ab5d-93ad0d323b68@xiplink.com","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-24T21:19:09Z","receivedAt":"2023-10-24T21:19:13Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Tue, Oct 24, 2023 at 10:01:07AM -0400, Marc Branchaud wrote:\n>I will only say that, I personally don't read man pages from \n>start-to-end like a novel. I jump to the part that explains the thing \n>I need to learn about. So I think your assumptions about what context \n>a reader might have in mind when they see this text are invalid.\n>\nwe are speaking about the context of a single paragraph, so that doesn't \nseem like a relevant objection.\n\n>> +The commit message for the folded commit is the concatenation of the\n>> +message of the first commit with those of commits identified by \"squash\"\n>\n>s/message of the first commit/picked commit's message/\n>\nthat does indeed sound better, but i think it's more confusing (and \npotentially even more so when translated directly). i guess one could \nuse \"pick'd commit's\", but that's kind of ugly again.\n\n>> +commands, omitting those of commits identified by \"fixup\" commands,\n>> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n>> +only from the \"fixup -c\" commit (having more than one of these is\n>> +incorrect).\n>\n>As Phillip said, this is wrong. I agree with Phillip that the \n>documentation should reflect the actual implementation, not what we hope \n>the implementation might be some day.\n>\nthere is also the middle ground of making it intentionally vague in \nanticipation of a possible change. my current draft says \"if multiple \nare present, the last one takes precedence, but this should not be \nrelied upon\".\n\n>> +The first commit which contributes to the suggested commit message \n>> also\n>\n>s/suggested/folded/ -- with \"fixup -C\" there is no \"suggested\" message.\n>\nthat's a good point, but i want to emphasize the fact that it's the \npre-edit message, i.e., that trimming down the squashed message doesn't \nchange anything.\nanyway, this part will be postponed to another contribution anyway (see \nparallel thread).\n\nthanks\n"},{"id":"483823","messageId":"ZTg3stQRcC1ZYFxj@ugly","threadId":"60417","inReplyTo":"ZTamhY1sTpp1N6n+@nand.local","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-24T21:31:30Z","receivedAt":"2023-10-24T21:31:33Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Mon, Oct 23, 2023 at 12:59:49PM -0400, Taylor Blau wrote:\n>The line wrapping is a little odd: it looks like each sentence begins \n>on a its own line.\n>\nthis is indeed the case.\n\n>Did you mean for there to be a visual separation between those \n>sentences in the rendered doc?\n>\nno.\n\nthe idea is to keep the churn down in later edits, by making reflowing \nthe entire paragraph visibly unnecesary. i can change it if it's deemed \ntoo weird.\n\nregards\n"},{"id":"483849","messageId":"20231025102932.1202299-1-oswald.buddenhagen@gmx.de","threadId":"60417","inReplyTo":"20231023130016.1093356-1-oswald.buddenhagen@gmx.de","subject":"[PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-25T10:29:32Z","receivedAt":"2023-10-25T10:29:38Z","isPatch":true,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"Create a clear top-down structure which makes it hopefully unambiguous\nwhat happens when.\n\nThe behavior in the presence of multiple \"fixup -c\" is somewhat\nquestionable, as arguably it would be better to complain about it rather\nthan letting the last instance win. But for the time being we document\nthe status quo, with a note that it is not guaranteed. Note that\nactually changing it would require --autosquash eliding the superseded\nuses.\n\nAlso emphasize that the author info of the first commit is preserved\neven in the presence of \"fixup -c\", as this diverges from \"git commit\n-c\"'s behavior. New options matching the latter should be introduced for\ncompleteness.\n\nSigned-off-by: Oswald Buddenhagen \n\n---\nv3:\n- adjust to reality, and elaborate in the commit message why it's\n arguably somewhat suboptimal\n\ni deliberated the 'command \"pick\"' word order swap suggested by marc,\nbut while it improves things locally, it somehow doesn't flow with the\n\"redundancy-reduced\" last part of the sentence.\n\nv2:\n- slight adjustments inspired by marc. however, i left most things\n unchanged or even went in the opposite direction, because i assume the\n readers to be sufficiently context-sensitive, and the objective is\n merely to be not actively confusing. adding redundancy in the name of\n clarity would just make the text stylistically inferior and arguably\n harder to read.\n\nCc: Junio C Hamano \nCc: Phillip Wood \nCc: Taylor Blau \nCc: Christian Couder \nCc: Charvi Mendiratta \nCc: Marc Branchaud \n---\n Documentation/git-rebase.txt | 30 ++++++++++++++++--------------\n 1 file changed, 16 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex e7b39ad244..578d1d34a6 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -890,20 +890,22 @@ command \"pick\" with the command \"reword\".\n To drop a commit, replace the command \"pick\" with \"drop\", or just\n delete the matching line.\n \n-If you want to fold two or more commits into one, replace the command\n-\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n-If the commits had different authors, the folded commit will be\n-attributed to the author of the first commit. The suggested commit\n-message for the folded commit is the concatenation of the first\n-commit's message with those identified by \"squash\" commands, omitting the\n-messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n-is used. In that case the suggested commit message is only the message\n-of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n-the message. The contents (patch) of the \"fixup -c\" commit are still\n-incorporated into the folded commit. If there is more than one \"fixup -c\"\n-commit, the message from the final one is used. You can also use\n-\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n-an editor.\n+If you want to fold two or more commits into one (that is, to combine\n+their contents/patches), replace the command \"pick\" for the second and\n+subsequent commits with \"squash\" or \"fixup\".\n+The commit message for the folded commit is the concatenation of the\n+message of the first commit with those of commits identified by \"squash\"\n+commands, omitting those of commits identified by \"fixup\" commands,\n+unless \"fixup -c\" is used. In the latter case, the message is obtained\n+only from the \"fixup -c\" commit (if multiple are present, the last one\n+takes precedence, but this should not be relied upon).\n+If the resulting commit message is a concatenation of multiple messages,\n+an editor is opened allowing you to edit it. This is also the case for a\n+message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n+the editor; this is analogous to the behavior of `git commit`.\n+The author information (including date/timestamp) always comes from\n+the first commit; this is the case even if \"fixup -c/-C\" is used,\n+contrary to what `git commit` does.\n \n `git rebase` will stop when \"pick\" has been replaced with \"edit\" or\n when a command fails due to merge errors. When you are done editing\n-- \n2.42.0.419.g70bf8a5751\n\n"},{"id":"483979","messageId":"b71d066b-104a-4c60-9319-b3c635be6efc@xiplink.com","threadId":"60417","inReplyTo":"ZTg0zXkvSQ6L+4Oj@ugly","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-27T12:39:03Z","receivedAt":"2023-10-27T12:39:07Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-24 17:19, Oswald Buddenhagen wrote:\n> \n>>> +The commit message for the folded commit is the concatenation of the\n>>> +message of the first commit with those of commits identified by \n>>> \"squash\"\n>>\n>> s/message of the first commit/picked commit's message/\n>>\n> that does indeed sound better, but i think it's more confusing (and \n> potentially even more so when translated directly). i guess one could \n> use \"pick'd commit's\", but that's kind of ugly again.\n\nLet the translators worry about how to phrase it in other languages. In \nEnglish \"picked\" is the right choice. You should not presume that other \nlanguages will want to use the word \"pick\" verbatim.\n\n\t\tM.\n"},{"id":"483985","messageId":"ZTu2V/cG35LBtUpo@ugly","threadId":"60417","inReplyTo":"b71d066b-104a-4c60-9319-b3c635be6efc@xiplink.com","subject":"Re: [RESEND v2] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-27T13:08:39Z","receivedAt":"2023-10-27T13:08:43Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Fri, Oct 27, 2023 at 08:39:03AM -0400, Marc Branchaud wrote:\n>On 2023-10-24 17:19, Oswald Buddenhagen wrote:\n>>>> +The commit message for the folded commit is the concatenation of \n>>>> the\n>>>> +message of the first commit with those of commits identified by \n>>>> \"squash\"\n>>>\n>>> s/message of the first commit/picked commit's message/\n>>>\n>> that does indeed sound better, but i think it's more confusing (and \n>> potentially even more so when translated directly). i guess one could \n>> use \"pick'd commit's\", but that's kind of ugly again.\n>\n>Let the translators worry about how to phrase it in other languages.\n>\nmy experience tells me that this isn't a good idea. translations are \noften done by people who have little domain knowledge of what they \ntranslate. it's a good idea to guide them.\nalso, the english text is often read by people who barely understand \nenglish, and will attempt literal translations in their head.\n\n>In English \"picked\" is the right choice.\n>\nthe squashed commits also fit the natural use of \"picked\", because \n\"picking\" means \"selecting\". it's not advisable to use this potentially \nambiguous term when there is an unambiguous alternative way to identify \nthe commit available.\n\n>You should not presume that other languages will want to use the word \n>\"pick\" verbatim.\n>\nwell, i actually should, because it's the command's own name, which \ndefinitely shouldn't be translated.\n\nregards\n"},{"id":"483986","messageId":"56e3e974-a027-439f-871d-c7fbae65a04e@xiplink.com","threadId":"60417","inReplyTo":"20231025102932.1202299-1-oswald.buddenhagen@gmx.de","subject":"Re: [PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-27T13:14:42Z","receivedAt":"2023-10-27T13:14:48Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-25 06:29, Oswald Buddenhagen wrote:\n> Create a clear top-down structure which makes it hopefully unambiguous\n> what happens when.\n> \n> The behavior in the presence of multiple \"fixup -c\" is somewhat\n> questionable, as arguably it would be better to complain about it rather\n> than letting the last instance win. But for the time being we document\n> the status quo, with a note that it is not guaranteed. Note that\n> actually changing it would require --autosquash eliding the superseded\n> uses.\n\nI do not think this kind of editorializing belongs in the commit's \nmessage, but this likely isn't the first commit message that expresses \nan opinion.\n\n> Also emphasize that the author info of the first commit is preserved\n> even in the presence of \"fixup -c\", as this diverges from \"git commit\n> -c\"'s behavior. New options matching the latter should be introduced for\n> completeness.\n> \n> Signed-off-by: Oswald Buddenhagen \n> \n> ---\n> v3:\n> - adjust to reality, and elaborate in the commit message why it's\n> arguably somewhat suboptimal\n> \n> i deliberated the 'command \"pick\"' word order swap suggested by marc,\n> but while it improves things locally, it somehow doesn't flow with the\n> \"redundancy-reduced\" last part of the sentence.\n> \n> v2:\n> - slight adjustments inspired by marc. however, i left most things\n> unchanged or even went in the opposite direction, because i assume the\n> readers to be sufficiently context-sensitive, and the objective is\n> merely to be not actively confusing. adding redundancy in the name of\n> clarity would just make the text stylistically inferior and arguably\n> harder to read.\n> \n> Cc: Junio C Hamano \n> Cc: Phillip Wood \n> Cc: Taylor Blau \n> Cc: Christian Couder \n> Cc: Charvi Mendiratta \n> Cc: Marc Branchaud \n> ---\n> Documentation/git-rebase.txt | 30 ++++++++++++++++--------------\n> 1 file changed, 16 insertions(+), 14 deletions(-)\n> \n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index e7b39ad244..578d1d34a6 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -890,20 +890,22 @@ command \"pick\" with the command \"reword\".\n> To drop a commit, replace the command \"pick\" with \"drop\", or just\n> delete the matching line.\n> \n> -If you want to fold two or more commits into one, replace the command\n> -\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n> -If the commits had different authors, the folded commit will be\n> -attributed to the author of the first commit. The suggested commit\n> -message for the folded commit is the concatenation of the first\n> -commit's message with those identified by \"squash\" commands, omitting the\n> -messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n> -is used. In that case the suggested commit message is only the message\n> -of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n> -the message. The contents (patch) of the \"fixup -c\" commit are still\n> -incorporated into the folded commit. If there is more than one \"fixup -c\"\n> -commit, the message from the final one is used. You can also use\n> -\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n> -an editor.\n> +If you want to fold two or more commits into one (that is, to combine\n> +their contents/patches), replace the command \"pick\" for the second and\n> +subsequent commits with \"squash\" or \"fixup\".\n> +The commit message for the folded commit is the concatenation of the\n> +message of the first commit with those of commits identified by \"squash\"\n> +commands, omitting those of commits identified by \"fixup\" commands,\n> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n> +only from the \"fixup -c\" commit (if multiple are present, the last one\n> +takes precedence, but this should not be relied upon).\n\nI like the overall phrasing here.\n\nBut I think you should remove the \"but this should not be relied upon\" \nphrase. This reads as if Git's current behaviour is undefined, which \nmost definitely is not true.\n\nEven changing this to something like \"but this might change in the \nfuture\" is unhelpful. Everything in Git is subject to change over a \nlong-enough time span, so the same could be said about every aspect of Git.\n\nUntil the behaviour actually changes, it's perfectly fine for people to \nuse multiple \"fixup -c\" commands. There's no reason to scare them off \nof it.\n\n> +If the resulting commit message is a concatenation of multiple messages,\n> +an editor is opened allowing you to edit it. This is also the case for a\n> +message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n> +the editor; this is analogous to the behavior of `git commit`.\n> +The author information (including date/timestamp) always comes from\n> +the first commit; this is the case even if \"fixup -c/-C\" is used,\n> +contrary to what `git commit` does.\n\nThis phrasing is much better.\n\nThanks for putting up with my pedantry!\n\n\t\tM.\n"},{"id":"483998","messageId":"ZTvhYSMOiaNbpTZ2@ugly","threadId":"60417","inReplyTo":"56e3e974-a027-439f-871d-c7fbae65a04e@xiplink.com","subject":"Re: [PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-27T16:12:17Z","receivedAt":"2023-10-27T16:12:20Z","isPatch":true,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Fri, Oct 27, 2023 at 09:14:42AM -0400, Marc Branchaud wrote:\n>On 2023-10-25 06:29, Oswald Buddenhagen wrote:\n>> The behavior in the presence of multiple \"fixup -c\" is somewhat\n>> questionable, as arguably it would be better to complain about it rather\n>> than letting the last instance win. But for the time being we document\n>> the status quo, with a note that it is not guaranteed. Note that\n>> actually changing it would require --autosquash eliding the superseded\n>> uses.\n>\n>I do not think this kind of editorializing belongs in the commit's \n>message, but this likely isn't the first commit message that expresses \n>an opinion.\n>\ncommmit messages should elaborate alternatives considered, which \nincludes ones which depend on changes that can be reasonably expected to \npossibly happen at some point.\n\n>But I think you should remove the \"but this should not be relied upon\" \n>phrase. This reads as if Git's current behaviour is undefined, which \n>most definitely is not true.\n>\n>Even changing this to something like \"but this might change in the \n>future\" is unhelpful. Everything in Git is subject to change over a \n>long-enough time span, so the same could be said about every aspect of Git.\n>\n>Until the behaviour actually changes, it's perfectly fine for people to \n>use multiple \"fixup -c\" commands. There's no reason to scare them off \n>of it.\n>\nthings can't change overnight; the resistance even the most trivial \nbehavior changes meet is enormous. so explicitly documenting long in \nadvance that something is subject to change is basically the only way to \nget it changed at all.\n\nspecifically for this feature, there is no reason at all to rely on this \nbehavior when hand-editing the todo list, and occurrences most likely \nindicate a mistake, which is why i would prefer it to be rejected.\n\nregards\n"},{"id":"484009","messageId":"xmqqh6mbod1b.fsf@gitster.g","threadId":"60417","inReplyTo":"56e3e974-a027-439f-871d-c7fbae65a04e@xiplink.com","subject":"Re: [PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-27T23:34:24Z","receivedAt":"2023-10-27T23:34:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> I do not think this kind of editorializing belongs in the commit's\n> message, but this likely isn't the first commit message that expresses\n> an opinion.\n\nThanks for saying this.\n\n> I like the overall phrasing here.\n>\n> But I think you should remove the \"but this should not be relied upon\"\n> phrase. This reads as if Git's current behaviour is undefined, which\n> most definitely is not true.\n>\n> Even changing this to something like \"but this might change in the\n> future\" is unhelpful. Everything in Git is subject to change over a\n> long-enough time span, so the same could be said about every aspect of\n> Git.\n>\n> Until the behaviour actually changes, it's perfectly fine for people\n> to use multiple \"fixup -c\" commands. There's no reason to scare them\n> off of it.\n\nAnd that would simplify the description to make it easier to follow\nby readers who are *not* involved in the development process.\n\n>\n>> +If the resulting commit message is a concatenation of multiple messages,\n>> +an editor is opened allowing you to edit it. This is also the case for a\n>> +message obtained via \"fixup -c\", while using \"fixup -C\" instead skips\n>> +the editor; this is analogous to the behavior of `git commit`.\n>> +The author information (including date/timestamp) always comes from\n>> +the first commit; this is the case even if \"fixup -c/-C\" is used,\n>> +contrary to what `git commit` does.\n>\n> This phrasing is much better.\n>\n> Thanks for putting up with my pedantry!\n\nThanks for a good review. I guess the patch is very near the finish\nline?\n\n"},{"id":"484092","messageId":"2daced1b-574e-442c-9cca-fa5050946f2f@gmail.com","threadId":"60417","inReplyTo":"56e3e974-a027-439f-871d-c7fbae65a04e@xiplink.com","subject":"Re: [PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-10-30T09:55:42Z","receivedAt":"2023-10-30T09:55:53Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 27/10/2023 14:14, Marc Branchaud wrote:\n>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n>> index e7b39ad244..578d1d34a6 100644\n>> --- a/Documentation/git-rebase.txt\n>> +++ b/Documentation/git-rebase.txt\n>> @@ -890,20 +890,22 @@ command \"pick\" with the command \"reword\".\n>>   To drop a commit, replace the command \"pick\" with \"drop\", or just\n>>   delete the matching line.\n>> -If you want to fold two or more commits into one, replace the command\n>> -\"pick\" for the second and subsequent commits with \"squash\" or \"fixup\".\n>> -If the commits had different authors, the folded commit will be\n>> -attributed to the author of the first commit.  The suggested commit\n>> -message for the folded commit is the concatenation of the first\n>> -commit's message with those identified by \"squash\" commands, omitting \n>> the\n>> -messages of commits identified by \"fixup\" commands, unless \"fixup -c\"\n>> -is used.  In that case the suggested commit message is only the message\n>> -of the \"fixup -c\" commit, and an editor is opened allowing you to edit\n>> -the message.  The contents (patch) of the \"fixup -c\" commit are still\n>> -incorporated into the folded commit. If there is more than one \"fixup \n>> -c\"\n>> -commit, the message from the final one is used.  You can also use\n>> -\"fixup -C\" to get the same behavior as \"fixup -c\" except without opening\n>> -an editor.\n>> +If you want to fold two or more commits into one (that is, to combine\n>> +their contents/patches), replace the command \"pick\" for the second and\n>> +subsequent commits with \"squash\" or \"fixup\".\n>> +The commit message for the folded commit is the concatenation of the\n>> +message of the first commit with those of commits identified by \"squash\"\n>> +commands, omitting those of commits identified by \"fixup\" commands,\n>> +unless \"fixup -c\" is used. In the latter case, the message is obtained\n>> +only from the \"fixup -c\" commit (if multiple are present, the last one\n>> +takes precedence, but this should not be relied upon).\n> \n> I like the overall phrasing here.\n> \n> But I think you should remove the \"but this should not be relied upon\" \n> phrase.  This reads as if Git's current behaviour is undefined, which \n> most definitely is not true.\n\nI agree it would be better to remove that phrase, as you say it makes it \nsounds like the behaviour cannot be relied on.\n\n> Even changing this to something like \"but this might change in the \n> future\" is unhelpful.  Everything in Git is subject to change over a \n> long-enough time span, so the same could be said about every aspect of Git.\n> \n> Until the behaviour actually changes, it's perfectly fine for people to \n> use multiple \"fixup -c\" commands.  There's no reason to scare them off \n> of it.\n\nIndeed\n\nBest Wishes\n\nPhillip\n"},{"id":"484242","messageId":"cc71b825-8283-44d0-a059-f2c069caebe3@xiplink.com","threadId":"60417","inReplyTo":"xmqqh6mbod1b.fsf@gitster.g","subject":"Re: [PATCH v3] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-31T18:48:19Z","receivedAt":"2023-10-31T18:48:24Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-27 19:34, Junio C Hamano wrote:\n> \n> Thanks for a good review. I guess the patch is very near the finish\n> line?\n\nYes. In my mind, all that's needed is to remove the part about \"should \nnot be relied upon\".\n\n\t\tM.\n"}]}