{"thread":{"id":"66604","subject":"[PATCH v3] doc: git-rebase: update incompatible options","startedAt":"2026-10-20T15:09:23Z","lastAt":"2026-10-20T18:16:09Z","messageCount":3,"participants":["Omri Sarig","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"555558","messageId":"20261020150923.5595-1-omri.sarig13@gmail.com","threadId":"66604","inReplyTo":null,"subject":"[PATCH v3] doc: git-rebase: update incompatible options","fromName":"Omri Sarig","fromEmail":"omri.sarig13@gmail.com","sentAt":"2026-10-20T15:09:23Z","receivedAt":"2026-10-20T15:09:23Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"Several options in the rebase man page link to the \"INCOMPATIBLE\nOPTIONS\" section when the option is no-longer incompatible with any\nother option.\n\n- Commit 1a66d8c6f6 (rebase: remove --allow-empty-message from\n  incompatible opts, 2023-01-25) removed \"--allow-empty-message\" from\n  the INCOMPATIBLE OPTIONS section, but did not remove the link to that\n  section from the option description.\n- Commit a74b35081c (rebase: drop support for `--preserve-merges`,\n  2021-09-07) removed the `--preserve-merges` option from rebase, which\n  removes all incompatbiilty references to `--ignore-date,\n  --reset-author-date` and `--signoff`.\n\nAdditionally, `--onto` doesn't link to the INCOMPATIBLE OPTIONS section, even\nthough it is incompatible with `--keep-base`.\n\nUpdate the description of these option, to have correct references to\nthe INCOMPATIBLE OPTIONS section.\n\nSigned-off-by: Omri Sarig <omri.sarig13@gmail.com>\n---\n\nThank you for the review!\n\nChanges in V2:\n- Update commit message per the review comments from Phillip (Thanks for the\n  review!).\n- Add `--onto` to INCOMPATIEBLE OPTIONS.\n\nChanges in V3:\n- Downcase \"Update\" in commit title\n\n Documentation/git-rebase.adoc | 8 ++------\n 1 file changed, 2 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex 6536ebdc90..6363b1a096 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -218,6 +218,8 @@ OPTIONS\n As a special case, you may use \"A\\...B\" as a shortcut for the\n merge base of A and B if there is exactly one merge base. You can\n leave out at most one of A and B, in which case it defaults to HEAD.\n++\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n See <<TRANSPLANTING,TRANSPLANTING A TOPIC BRANCH WITH --ONTO>>\n above for examples.\n@@ -334,8 +336,6 @@ See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \tand this option would override that behavior, allowing commits\n \twith empty messages to be rebased.  Now commits with an empty\n \tmessage do not cause rebasing to halt.\n-+\n-See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -m::\n --merge::\n@@ -489,15 +489,11 @@ applying (in terms of the author date).\n \tInstead of using the author date of the original commit, use\n \tthe current time as the\tauthor date of the rebased commit.  This\n \toption implies `--force-rebase`.\n-+\n-See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --signoff::\n \tAdd a `Signed-off-by` trailer to all the rebased commits. Note\n \tthat if `--interactive` is given then only commits marked to be\n \tpicked, edited or reworded will have the trailer added.\n-+\n-See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --trailer=<trailer>::\n \tAppend the given trailer to every rebased commit message, processed\n\n"},{"id":"555577","messageId":"xmqqjyncxrur.fsf@gitster.g","threadId":"66604","inReplyTo":"20261020150923.5595-1-omri.sarig13@gmail.com","subject":"Re: [PATCH v3] doc: git-rebase: update incompatible options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-20T16:24:28Z","receivedAt":"2026-10-20T16:24:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Omri Sarig <omri.sarig13@gmail.com> writes:\n\n> Several options in the rebase man page link to the \"INCOMPATIBLE\n> OPTIONS\" section when the option is no-longer incompatible with any\n> other option.\n\nThere are several options listed in the section, but only two of\nthem are \"no longer incompatible\".  So either:\n\n    Several options in the rebase manual page link to the\n    \"INCOMPATIBLE OPTIONS\" section, but a few of them are no longer\n    incompatible with any other option.\n\nor:\n\n    A few options in the rebase manual page link to the\n    \"INCOMPATIBLE OPTIONS\" section, but they are no longer\n    incompatible with any other option.\n\n\n\n> - Commit 1a66d8c6f6 (rebase: remove --allow-empty-message from\n>   incompatible opts, 2023-01-25) removed \"--allow-empty-message\" from\n>   the INCOMPATIBLE OPTIONS section, but did not remove the link to that\n>   section from the option description.\n> - Commit a74b35081c (rebase: drop support for `--preserve-merges`,\n>   2021-09-07) removed the `--preserve-merges` option from rebase, which\n>   removes all incompatbiilty references to `--ignore-date,\n>   --reset-author-date` and `--signoff`.\n\nAfter seeing the explanation for the above two options ...\n\n> Additionally, `--onto` doesn't link to the INCOMPATIBLE OPTIONS section, even\n> though it is incompatible with `--keep-base`.\n\n... readers would naturally want to know when this happened.  It\nseems that when the '--keep-base' option was introduced at\n414d924beb (rebase: teach rebase --keep-base, 2019-08-27), the\ndescription for '--keep-base' had the \"see incompatible options\nbelow\" but the one for '--onto' was not updated, and the manual\nstayed that way ever since.\n\n> Update the description of these option, to have correct references to\n> the INCOMPATIBLE OPTIONS section.\n\n\"these option\" -> \"these options\".\n\nAlso, notice the commonality across these three commits?  They all\npredate the latest tagged release Git 2.56, so as a fix, a change\nlike this should be prepared to be applicable to the maintenance\ntrack for that release.  When queuing the last round (v2), I wiggled\nthe patch to apply on v2.56.0 while running \"git am -3\", but perhaps\nit would be simpler if you prepared your patch on v2.56.0 on your\nend?\n\nFYI, here is what I queued for v2.\n\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..b84b14f02e 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -217,6 +217,8 @@ OPTIONS\n As a special case, you may use \"A\\...B\" as a shortcut for the\n merge base of A and B if there is exactly one merge base. You can\n leave out at most one of A and B, in which case it defaults to HEAD.\n++\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.\n \n@@ -332,8 +334,6 @@ See also INCOMPATIBLE OPTIONS below.\n \tand this option would override that behavior, allowing commits\n \twith empty messages to be rebased.  Now commits with an empty\n \tmessage do not cause rebasing to halt.\n-+\n-See also INCOMPATIBLE OPTIONS below.\n \n -m::\n --merge::\n@@ -487,15 +487,11 @@ applying (in terms of the author date).\n \tInstead of using the author date of the original commit, use\n \tthe current time as the\tauthor date of the rebased commit.  This\n \toption implies `--force-rebase`.\n-+\n-See also INCOMPATIBLE OPTIONS below.\n \n --signoff::\n \tAdd a `Signed-off-by` trailer to all the rebased commits. Note\n \tthat if `--interactive` is given then only commits marked to be\n \tpicked, edited or reworded will have the trailer added.\n-+\n-See also INCOMPATIBLE OPTIONS below.\n \n --trailer=<trailer>::\n \tAppend the given trailer to every rebased commit message, processed\n\n"},{"id":"555588","messageId":"fce11abe-6d7e-495a-8729-c3a62c52c113@gmail.com","threadId":"66604","inReplyTo":"xmqqjyncxrur.fsf@gitster.g","subject":"Re: [PATCH v3] doc: git-rebase: update incompatible options","fromName":"Omri Sarig","fromEmail":"omri.sarig13@gmail.com","sentAt":"2026-10-20T18:16:09Z","receivedAt":"2026-10-20T18:16:09Z","isPatch":true,"sender":{"key":"omri.sarig13@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42355507?v=4"},"body":"\nOn 20/10/2026 18.24, Junio C Hamano wrote:\n> Omri Sarig <omri.sarig13@gmail.com> writes:\n>\n>> Several options in the rebase man page link to the \"INCOMPATIBLE\n>> OPTIONS\" section when the option is no-longer incompatible with any\n>> other option.\n> There are several options listed in the section, but only two of\n> them are \"no longer incompatible\".  So either:\n>\n>      Several options in the rebase manual page link to the\n>      \"INCOMPATIBLE OPTIONS\" section, but a few of them are no longer\n>      incompatible with any other option.\n>\n> or:\n>\n>      A few options in the rebase manual page link to the\n>      \"INCOMPATIBLE OPTIONS\" section, but they are no longer\n>      incompatible with any other option.\nWill do!\n>\n>\n>> - Commit 1a66d8c6f6 (rebase: remove --allow-empty-message from\n>>    incompatible opts, 2023-01-25) removed \"--allow-empty-message\" from\n>>    the INCOMPATIBLE OPTIONS section, but did not remove the link to that\n>>    section from the option description.\n>> - Commit a74b35081c (rebase: drop support for `--preserve-merges`,\n>>    2021-09-07) removed the `--preserve-merges` option from rebase, which\n>>    removes all incompatbiilty references to `--ignore-date,\n>>    --reset-author-date` and `--signoff`.\n> After seeing the explanation for the above two options ...\n>\n>> Additionally, `--onto` doesn't link to the INCOMPATIBLE OPTIONS section, even\n>> though it is incompatible with `--keep-base`.\n> ... readers would naturally want to know when this happened.  It\n> seems that when the '--keep-base' option was introduced at\n> 414d924beb (rebase: teach rebase --keep-base, 2019-08-27), the\n> description for '--keep-base' had the \"see incompatible options\n> below\" but the one for '--onto' was not updated, and the manual\n> stayed that way ever since.\nThat makes sense, I'll add it.\n>> Update the description of these option, to have correct references to\n>> the INCOMPATIBLE OPTIONS section.\n> \"these option\" -> \"these options\".\nWill do!\n>\n> Also, notice the commonality across these three commits?  They all\n> predate the latest tagged release Git 2.56, so as a fix, a change\n> like this should be prepared to be applicable to the maintenance\n> track for that release.  When queuing the last round (v2), I wiggled\n> the patch to apply on v2.56.0 while running \"git am -3\", but perhaps\n> it would be simpler if you prepared your patch on v2.56.0 on your\n> end?\n\nSorry, will fix.\nI've read the SubmittingPatches#choose-starting-point documentation now, and\nwill know for next time.\n\n>\n> FYI, here is what I queued for v2.\n>\n>\n> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\n> index f6c22d1598..b84b14f02e 100644\n> --- a/Documentation/git-rebase.adoc\n> +++ b/Documentation/git-rebase.adoc\n> @@ -217,6 +217,8 @@ OPTIONS\n>   As a special case, you may use \"A\\...B\" as a shortcut for the\n>   merge base of A and B if there is exactly one merge base. You can\n>   leave out at most one of A and B, in which case it defaults to HEAD.\n> ++\n> +See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\nGiven that the maintenance branch predates 2fc11e3382 (doc: add more AsciiDoc\ncross-references, 2026-09-25), none of the other lines have the AsciiDoc\nlink.\nI'd expect this change to be:\n\n++\n+See also INCOMPATIBLE OPTIONS below.\n\nto match the rest of the messages in this file.\n\nIs this correct, or should my patch include the \"final\" version of the line,\nwith the AsciiDoc link?\n\nIn case the line should be without a link, I guess that the link will be added\nduring one of the merges? Should I provide any help/support for that in the\ncurrent patchset?\n>   >   See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.\n>   > @@ -332,8 +334,6 @@ See also INCOMPATIBLE OPTIONS below.\n>   \tand this option would override that behavior, allowing commits\n>   \twith empty messages to be rebased.  Now commits with an empty\n>   \tmessage do not cause rebasing to halt.\n> -+\n> -See also INCOMPATIBLE OPTIONS below.\n>   >   -m::\n>   --merge::\n> @@ -487,15 +487,11 @@ applying (in terms of the author date).\n>   \tInstead of using the author date of the original commit, use\n>   \tthe current time as the\tauthor date of the rebased commit.  This\n>   \toption implies `--force-rebase`.\n> -+\n> -See also INCOMPATIBLE OPTIONS below.\n>   >   --signoff::\n>   \tAdd a `Signed-off-by` trailer to all the rebased commits. Note\n>   \tthat if `--interactive` is given then only commits marked to be\n>   \tpicked, edited or reworded will have the trailer added.\n> -+\n> -See also INCOMPATIBLE OPTIONS below.\n>   >   --trailer=<trailer>::\n>   \tAppend the given trailer to every rebased commit message, processed\nThank you for the review, it is really appreciated.\n\n"}]}