git-rebase.txt: document incompatible options

git rebase has many options that only work with one of its three backends.
It also has a few other pairs of incompatible options.  Document these.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Elijah Newren 2018-06-25 09:12:52 -07:00 committed by Junio C Hamano
parent 53f9a3e157
commit 5dacd4abdd

View File

@ -243,11 +243,15 @@ leave out at most one of A and B, in which case it defaults to HEAD.
--keep-empty:: --keep-empty::
Keep the commits that do not change anything from its Keep the commits that do not change anything from its
parents in the result. parents in the result.
+
See also INCOMPATIBLE OPTIONS below.
--allow-empty-message:: --allow-empty-message::
By default, rebasing commits with an empty message will fail. By default, rebasing commits with an empty message will fail.
This option overrides that behavior, allowing commits with empty This option overrides that behavior, allowing commits with empty
messages to be rebased. messages to be rebased.
+
See also INCOMPATIBLE OPTIONS below.
--skip:: --skip::
Restart the rebasing process by skipping the current patch. Restart the rebasing process by skipping the current patch.
@ -271,6 +275,8 @@ branch on top of the <upstream> branch. Because of this, when a merge
conflict happens, the side reported as 'ours' is the so-far rebased conflict happens, the side reported as 'ours' is the so-far rebased
series, starting with <upstream>, and 'theirs' is the working branch. In series, starting with <upstream>, and 'theirs' is the working branch. In
other words, the sides are swapped. other words, the sides are swapped.
+
See also INCOMPATIBLE OPTIONS below.
-s <strategy>:: -s <strategy>::
--strategy=<strategy>:: --strategy=<strategy>::
@ -280,8 +286,10 @@ other words, the sides are swapped.
+ +
Because 'git rebase' replays each commit from the working branch Because 'git rebase' replays each commit from the working branch
on top of the <upstream> branch using the given strategy, using on top of the <upstream> branch using the given strategy, using
the 'ours' strategy simply discards all patches from the <branch>, the 'ours' strategy simply empties all patches from the <branch>,
which makes little sense. which makes little sense.
+
See also INCOMPATIBLE OPTIONS below.
-X <strategy-option>:: -X <strategy-option>::
--strategy-option=<strategy-option>:: --strategy-option=<strategy-option>::
@ -289,6 +297,8 @@ which makes little sense.
This implies `--merge` and, if no strategy has been This implies `--merge` and, if no strategy has been
specified, `-s recursive`. Note the reversal of 'ours' and specified, `-s recursive`. Note the reversal of 'ours' and
'theirs' as noted above for the `-m` option. 'theirs' as noted above for the `-m` option.
+
See also INCOMPATIBLE OPTIONS below.
-S[<keyid>]:: -S[<keyid>]::
--gpg-sign[=<keyid>]:: --gpg-sign[=<keyid>]::
@ -324,6 +334,8 @@ which makes little sense.
and after each change. When fewer lines of surrounding and after each change. When fewer lines of surrounding
context exist they all must match. By default no context is context exist they all must match. By default no context is
ever ignored. ever ignored.
+
See also INCOMPATIBLE OPTIONS below.
-f:: -f::
--force-rebase:: --force-rebase::
@ -355,19 +367,22 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`.
--whitespace=<option>:: --whitespace=<option>::
These flag are passed to the 'git apply' program These flag are passed to the 'git apply' program
(see linkgit:git-apply[1]) that applies the patch. (see linkgit:git-apply[1]) that applies the patch.
Incompatible with the --interactive option. +
See also INCOMPATIBLE OPTIONS below.
--committer-date-is-author-date:: --committer-date-is-author-date::
--ignore-date:: --ignore-date::
These flags are passed to 'git am' to easily change the dates These flags are passed to 'git am' to easily change the dates
of the rebased commits (see linkgit:git-am[1]). of the rebased commits (see linkgit:git-am[1]).
Incompatible with the --interactive option. +
See also INCOMPATIBLE OPTIONS below.
--signoff:: --signoff::
Add a Signed-off-by: trailer to all the rebased commits. Note Add a Signed-off-by: trailer to all the rebased commits. Note
that if `--interactive` is given then only commits marked to be that if `--interactive` is given then only commits marked to be
picked, edited or reworded will have the trailer added. Incompatible picked, edited or reworded will have the trailer added.
with the `--preserve-merges` option. +
See also INCOMPATIBLE OPTIONS below.
-i:: -i::
--interactive:: --interactive::
@ -378,6 +393,8 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`.
The commit list format can be changed by setting the configuration option The commit list format can be changed by setting the configuration option
rebase.instructionFormat. A customized instruction format will automatically rebase.instructionFormat. A customized instruction format will automatically
have the long commit hash prepended to the format. have the long commit hash prepended to the format.
+
See also INCOMPATIBLE OPTIONS below.
-r:: -r::
--rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: --rebase-merges[=(rebase-cousins|no-rebase-cousins)]::
@ -404,7 +421,7 @@ It is currently only possible to recreate the merge commits using the
`recursive` merge strategy; Different merge strategies can be used only via `recursive` merge strategy; Different merge strategies can be used only via
explicit `exec git merge -s <strategy> [...]` commands. explicit `exec git merge -s <strategy> [...]` commands.
+ +
See also REBASING MERGES below. See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
-p:: -p::
--preserve-merges:: --preserve-merges::
@ -415,6 +432,8 @@ See also REBASING MERGES below.
This uses the `--interactive` machinery internally, but combining it This uses the `--interactive` machinery internally, but combining it
with the `--interactive` option explicitly is generally not a good with the `--interactive` option explicitly is generally not a good
idea unless you know what you are doing (see BUGS below). idea unless you know what you are doing (see BUGS below).
+
See also INCOMPATIBLE OPTIONS below.
-x <cmd>:: -x <cmd>::
--exec <cmd>:: --exec <cmd>::
@ -437,6 +456,8 @@ squash/fixup series.
+ +
This uses the `--interactive` machinery internally, but it can be run This uses the `--interactive` machinery internally, but it can be run
without an explicit `--interactive`. without an explicit `--interactive`.
+
See also INCOMPATIBLE OPTIONS below.
--root:: --root::
Rebase all commits reachable from <branch>, instead of Rebase all commits reachable from <branch>, instead of
@ -447,6 +468,8 @@ without an explicit `--interactive`.
When used together with both --onto and --preserve-merges, When used together with both --onto and --preserve-merges,
'all' root commits will be rewritten to have <newbase> as parent 'all' root commits will be rewritten to have <newbase> as parent
instead. instead.
+
See also INCOMPATIBLE OPTIONS below.
--autosquash:: --autosquash::
--no-autosquash:: --no-autosquash::
@ -461,11 +484,11 @@ without an explicit `--interactive`.
too. The recommended way to create fixup/squash commits is by using too. The recommended way to create fixup/squash commits is by using
the `--fixup`/`--squash` options of linkgit:git-commit[1]. the `--fixup`/`--squash` options of linkgit:git-commit[1].
+ +
This option is only valid when the `--interactive` option is used.
+
If the `--autosquash` option is enabled by default using the If the `--autosquash` option is enabled by default using the
configuration variable `rebase.autoSquash`, this option can be configuration variable `rebase.autoSquash`, this option can be
used to override and disable this setting. used to override and disable this setting.
+
See also INCOMPATIBLE OPTIONS below.
--autostash:: --autostash::
--no-autostash:: --no-autostash::
@ -487,6 +510,52 @@ recreates the topic branch with fresh commits so it can be remerged
successfully without needing to "revert the reversion" (see the successfully without needing to "revert the reversion" (see the
link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
INCOMPATIBLE OPTIONS
--------------------
git-rebase has many flags that are incompatible with each other,
predominantly due to the fact that it has three different underlying
implementations:
* one based on linkgit:git-am[1] (the default)
* one based on git-merge-recursive (merge backend)
* one based on linkgit:git-cherry-pick[1] (interactive backend)
Flags only understood by the am backend:
* --committer-date-is-author-date
* --ignore-date
* --whitespace
* --ignore-whitespace
* -C
Flags understood by both merge and interactive backends:
* --merge
* --strategy
* --strategy-option
* --allow-empty-message
Flags only understood by the interactive backend:
* --[no-]autosquash
* --rebase-merges
* --preserve-merges
* --interactive
* --exec
* --keep-empty
* --autosquash
* --edit-todo
* --root when used in combination with --onto
Other incompatible flag pairs:
* --preserve-merges and --interactive
* --preserve-merges and --signoff
* --preserve-merges and --rebase-merges
* --rebase-merges and --strategy
* --rebase-merges and --strategy-option
include::merge-strategies.txt[] include::merge-strategies.txt[]
NOTES NOTES