{"thread":{"id":"60405","subject":"[RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","startedAt":"2023-10-20T09:27:13Z","lastAt":"2023-10-21T07:26:27Z","messageCount":6,"participants":["Oswald Buddenhagen","Marc Branchaud","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"483547","messageId":"20231020092707.917514-1-oswald.buddenhagen@gmx.de","threadId":"60405","inReplyTo":null,"subject":"[RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-20T09:27:07Z","receivedAt":"2023-10-20T09:27:13Z","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---\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..857e025361 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+first commit's message with those identified by \"squash\" commands,\n+omitting the messages of commits identified by \"fixup\" commands, unless\n+\"fixup -c\" is used. In the latter case, the message is obtained only\n+from the \"fixup -c\" commit (having more than one \"fixup -c\" commit\n+makes no sense, and only the message from the last one is used).\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":"483602","messageId":"841c3b59-9e7c-4492-9d66-8af42c3222ea@xiplink.com","threadId":"60405","inReplyTo":"20231020092707.917514-1-oswald.buddenhagen@gmx.de","subject":"Re: [RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-20T21:40:01Z","receivedAt":"2023-10-20T21:40:11Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-20 05:27, 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\nI think this is a definite improvement to the text. Thanks for working \non this! I do have a few suggestions, below.\n\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..857e025361 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> +first commit's message with those identified by \"squash\" commands,\n\nI think the original text's \"those identified by\" is a bit vague: Does \n\"those\" mean \"messages\" or \"commits\"? The sentence reads like \"those\" \nstands for \"messages\", but then of course you don't identify *messages* \nwith \"squash\" commands.\n\nMaybe\n\tthose from commits identified by\n?\n\n> +omitting the messages of commits identified by \"fixup\" commands, unless\n> +\"fixup -c\" is used. In the latter case, the message is obtained only\n> +from the \"fixup -c\" commit\n\nI think it's worth emphasizing that \"fixup -c\" also drops the message \nfrom the initial \"pick\" commit as well as all the \"squash\" commits (I \npresume that's the case, I haven't tried it [1]).\n\nMaybe emphasize the word \"only\" in the sentence (i.e. spell it as \n'only'). To really drive the point home it could say something like\n\tobtained 'only' from the \"fixup -c\" commit, dropping the\n\tmessages of all the other involved commits\n\n> (having more than one \"fixup -c\" commit\n> +makes no sense, and only the message from the last one is used).\n\n\"Makes no sense\" seems a bit opinionated (although I agree with the \nsentiment). Also, you can legitimately have more than one \"fixup -c\" in \nthe overall instruction set, as long as there's at least one \"pick\" \ncommand in between, e.g.\n\tpick 1111beef\n\tfixup 2222f00d\n\tfixup -c 3333ab1e\n\tpick 4444d00d\n\tfixup 5555feed\n\tfixup -c 6666dead\n\nHow about\n\t(if more than one \"fixup -c\" command appears in a sequence\n\tof \"fixup\" and \"squash\" commands, only the message from\n\tthe last \"fixup -c\" commit is used)\n\nThanks,\n\n\t\tM.\n\n[1] Makes me wonder if rebase should also support \"squash -c\"...\n"},{"id":"483609","messageId":"xmqq1qdoq3tt.fsf@gitster.g","threadId":"60405","inReplyTo":"841c3b59-9e7c-4492-9d66-8af42c3222ea@xiplink.com","subject":"Re: [RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-20T23:19:58Z","receivedAt":"2023-10-20T23:20:04Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> [1] Makes me wonder if rebase should also support \"squash -c\"...\n\nHow would it be different from \"fixup -c\", though?\n\nA \"pick\" followed by either \"fixup -c\" or \"squash -c\" will have the\nsame effect on the contents (i.e., apply the changes both commits\nwant to make to their respective parents) and present the end user\nan editor buffer filled with the commit specified by the \"-c\"\noption, right?\n\nOr am I missing something?\n"},{"id":"483611","messageId":"b5bc179d-46b6-4c48-bfe5-769dac38489b@xiplink.com","threadId":"60405","inReplyTo":"xmqq1qdoq3tt.fsf@gitster.g","subject":"Re: [RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2023-10-20T23:56:09Z","receivedAt":"2023-10-20T23:56:16Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"\nOn 2023-10-20 19:19, Junio C Hamano wrote:\n> Marc Branchaud writes:\n> \n>> [1] Makes me wonder if rebase should also support \"squash -c\"...\n> \n> How would it be different from \"fixup -c\", though?\n> \n> A \"pick\" followed by either \"fixup -c\" or \"squash -c\" will have the\n> same effect on the contents (i.e., apply the changes both commits\n> want to make to their respective parents) and present the end user\n> an editor buffer filled with the commit specified by the \"-c\"\n> option, right?\n> \n> Or am I missing something?\n\nNo, you're not.\n\nI should have added \"as a convenience\". Squash and fixup are similar \nenough that it seems reasonable for them to both support -c. Saves \npeople from having to remember that only fixup allows -c.\n\n\t\tM.\n"},{"id":"483612","messageId":"xmqqsf64omdi.fsf@gitster.g","threadId":"60405","inReplyTo":"b5bc179d-46b6-4c48-bfe5-769dac38489b@xiplink.com","subject":"Re: [RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-21T00:22:17Z","receivedAt":"2023-10-21T00:22:27Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> I should have added \"as a convenience\". Squash and fixup are similar\n> enough that it seems reasonable for them to both support -c. Saves\n> people from having to remember that only fixup allows -c.\n\nYeah, \"fixup\" could have been a plain \"squash\" with some option. It\ncould have been two options, \"-i\" (\"ignore message of this one\") and\n\"-o\" (\"use message of this one alone\"), and then today's \"fixup\"\nwould have been \"squash -i\", and today's \"fixup -c\" would have been\n\"squash -o\".\n\nBut I agree that \"squash -c\" is something one may find tempting to\ntype, after learning \"fixup -c\".\n\nI forgot to comment on the real contents of your review, by the way.\nEverything you said was reasonable.\n\n"},{"id":"483616","messageId":"ZTN9HgqH01iN2CGr@ugly","threadId":"60405","inReplyTo":"841c3b59-9e7c-4492-9d66-8af42c3222ea@xiplink.com","subject":"Re: [RESEND] git-rebase.txt: rewrite docu for fixup/squash (again)","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-10-21T07:26:22Z","receivedAt":"2023-10-21T07:26:27Z","isPatch":false,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Fri, Oct 20, 2023 at 05:40:01PM -0400, Marc Branchaud wrote:\n>I think the original text's \"those identified by\" is a bit vague: Does \n>\"those\" mean \"messages\" or \"commits\"? The sentence reads like \"those\" \n>stands for \"messages\", but then of course you don't identify *messages* \n>with \"squash\" commands.\n>\nfair enough, though the repetition makes it linguistically inferior.\n\n>Maybe emphasize the word \"only\" in the sentence (i.e. spell it as \n>'only'). \n>\nthat seems excessive to me. i'm not assuming that my readers are dumb.\n\n> To really drive the point home it could say something like\n>\tobtained 'only' from the \"fixup -c\" commit, dropping the\n>\tmessages of all the other involved commits\n>\nas above.\n\nalso, i'm actually uneasy about including the exact behavior in the \nfirst place, as it codifies something questionable - a better response \nfrom git would be complaining about it. i will drop it.\n\n>> (having more than one \"fixup -c\" commit\n>> +makes no sense, and only the message from the last one is used).\n>\n>\"Makes no sense\" seems a bit opinionated (although I agree with the \n>sentiment).\n>\ni'm not terribly worried about readers who have an aversion towards \nbeing told facts ...\nanyway, i will use \"is incorrect\" instead, as it seems more to the \npoint.\n\n>Also, you can legitimately have more than one \"fixup -c\" in the overall \n>instruction set, as long as there's at least one \"pick\" command in \n>between, e.g.\n>\nyes, but the context is a single fixup sequence. the above comments \nabout readers and repetition apply here, too.\n\n>[1] Makes me wonder if rebase should also support \"squash -c\"...\n>\nthe distinction is that \"squash\" combines the messages, while \"fixup\" \ndiscards them, and the -c merely changes what is discarded. softening \nthat up seems counter-productive to me.\n\nthanks\n"}]}