git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v3] doc: git-rebase: update incompatible options

From
Junio C Hamano <gitster@pobox.com>
Date
Oct 20, 2026, 16:24 UTC
Message-ID
<xmqqjyncxrur.fsf@gitster.g>
In-Reply-To
<20261020150923.5595-1-omri.sarig13@gmail.com>
Omri Sarig <omri.sarig13@gmail.com> writes:
> Several options in the rebase man page link to the "INCOMPATIBLE
> OPTIONS" section when the option is no-longer incompatible with any
> other option.

There are several options listed in the section, but only two of them are "no longer incompatible". So either:

    Several options in the rebase manual page link to the
    "INCOMPATIBLE OPTIONS" section, but a few of them are no longer
    incompatible with any other option.
or:
    A few options in the rebase manual page link to the
    "INCOMPATIBLE OPTIONS" section, but they are no longer
    incompatible with any other option.
Show 8 quoted lines
> - Commit 1a66d8c6f6 (rebase: remove --allow-empty-message from
>   incompatible opts, 2023-01-25) removed "--allow-empty-message" from
>   the INCOMPATIBLE OPTIONS section, but did not remove the link to that
>   section from the option description.
> - Commit a74b35081c (rebase: drop support for `--preserve-merges`,
>   2021-09-07) removed the `--preserve-merges` option from rebase, which
>   removes all incompatbiilty references to `--ignore-date,
>   --reset-author-date` and `--signoff`.
After seeing the explanation for the above two options ...
> Additionally, `--onto` doesn't link to the INCOMPATIBLE OPTIONS section, even
> though it is incompatible with `--keep-base`.

... readers would naturally want to know when this happened. It seems that when the '--keep-base' option was introduced at 414d924beb (rebase: teach rebase --keep-base, 2019-08-27), the description for '--keep-base' had the "see incompatible options below" but the one for '--onto' was not updated, and the manual stayed that way ever since.

> Update the description of these option, to have correct references to
> the INCOMPATIBLE OPTIONS section.
"these option" -> "these options".

Also, notice the commonality across these three commits? They all predate the latest tagged release Git 2.56, so as a fix, a change like this should be prepared to be applicable to the maintenance track for that release. When queuing the last round (v2), I wiggled the patch to apply on v2.56.0 while running "git am -3", but perhaps it would be simpler if you prepared your patch on v2.56.0 on your end?

FYI, here is what I queued for v2.
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index f6c22d1598..b84b14f02e 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -217,6 +217,8 @@ OPTIONS
 As a special case, you may use "A\...B" as a shortcut for the
 merge base of A and B if there is exactly one merge base. You can
 leave out at most one of A and B, in which case it defaults to HEAD.
++
+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.
 
 See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.
 
@@ -332,8 +334,6 @@ See also INCOMPATIBLE OPTIONS below.
 	and this option would override that behavior, allowing commits
 	with empty messages to be rebased.  Now commits with an empty
 	message do not cause rebasing to halt.
-+
-See also INCOMPATIBLE OPTIONS below.
 
 -m::
 --merge::
@@ -487,15 +487,11 @@ applying (in terms of the author date).
 	Instead of using the author date of the original commit, use
 	the current time as the	author date of the rebased commit.  This
 	option implies `--force-rebase`.
-+
-See also INCOMPATIBLE OPTIONS below.
 
 --signoff::
 	Add a `Signed-off-by` trailer to all the rebased commits. Note
 	that if `--interactive` is given then only commits marked to be
 	picked, edited or reworded will have the trailer added.
-+
-See also INCOMPATIBLE OPTIONS below.
 
 --trailer=<trailer>::
 	Append the given trailer to every rebased commit message, processed
Previous: Omri SarigNext: Omri Sarig
Message 2 of 3 in “doc: git-rebase: update incompatible options”
  1. doc: git-rebase: update incompatible optionsOmri Sarig, Oct 20, 2026
  2. Junio C HamanoOct 20, 2026
  3. Omri SarigOct 20, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.