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>
Elijah Newren committed
Jun 25, 2018 at 09:12 UTC
5dacd4abdd3ce120b7c206b3a7184f9e0c83781a
1 file changed
+77
-8
Documentation/git-rebase.txt
+77
-8
@@ -243,11 +243,15 @@ leave out at most one of A and B, in which case it defaults to HEAD.
243
--keep-empty::
244
Keep the commits that do not change anything from its
245
parents in the result.
246
++
247
+See also INCOMPATIBLE OPTIONS below.
248
249
--allow-empty-message::
250
By default, rebasing commits with an empty message will fail.
251
This option overrides that behavior, allowing commits with empty
252
messages to be rebased.
253
++
254
+See also INCOMPATIBLE OPTIONS below.
255
256
--skip::
257
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
275
conflict happens, the side reported as 'ours' is the so-far rebased
276
series, starting with <upstream>, and 'theirs' is the working branch. In
277
other words, the sides are swapped.
278
++
279
+See also INCOMPATIBLE OPTIONS below.
280
281
-s <strategy>::
282
--strategy=<strategy>::
@@ -280,8 +286,10 @@ other words, the sides are swapped.
286
+
287
Because 'git rebase' replays each commit from the working branch
288
on top of the <upstream> branch using the given strategy, using
283
-the 'ours' strategy simply discards all patches from the <branch>,
289
+the 'ours' strategy simply empties all patches from the <branch>,
290
which makes little sense.
291
++
292
+See also INCOMPATIBLE OPTIONS below.
293
294
-X <strategy-option>::
295
--strategy-option=<strategy-option>::
@@ -289,6 +297,8 @@ which makes little sense.
297
This implies `--merge` and, if no strategy has been
298
specified, `-s recursive`. Note the reversal of 'ours' and
299
'theirs' as noted above for the `-m` option.
300
++
301
+See also INCOMPATIBLE OPTIONS below.
302
303
-S[<keyid>]::
304
--gpg-sign[=<keyid>]::
@@ -324,6 +334,8 @@ which makes little sense.
334
and after each change. When fewer lines of surrounding
335
context exist they all must match. By default no context is
336
ever ignored.
337
++
338
+See also INCOMPATIBLE OPTIONS below.
339
340
-f::
341
--force-rebase::
@@ -355,19 +367,22 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`.
367
--whitespace=<option>::
368
These flag are passed to the 'git apply' program
369
(see linkgit:git-apply[1]) that applies the patch.
358
- Incompatible with the --interactive option.
370
++
371
+See also INCOMPATIBLE OPTIONS below.
372
373
--committer-date-is-author-date::
374
--ignore-date::
375
These flags are passed to 'git am' to easily change the dates
376
of the rebased commits (see linkgit:git-am[1]).
364
- Incompatible with the --interactive option.
377
++
378
+See also INCOMPATIBLE OPTIONS below.
379
380
--signoff::
381
Add a Signed-off-by: trailer to all the rebased commits. Note
382
that if `--interactive` is given then only commits marked to be
369
- picked, edited or reworded will have the trailer added. Incompatible
370
- with the `--preserve-merges` option.
383
+ picked, edited or reworded will have the trailer added.
384
++
385
+See also INCOMPATIBLE OPTIONS below.
386
387
-i::
388
--interactive::
@@ -378,6 +393,8 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`.
393
The commit list format can be changed by setting the configuration option
394
rebase.instructionFormat. A customized instruction format will automatically
395
have the long commit hash prepended to the format.
396
++
397
+See also INCOMPATIBLE OPTIONS below.
398
399
-r::
400
--rebase-merges[=(rebase-cousins|no-rebase-cousins)]::
@@ -404,7 +421,7 @@ It is currently only possible to recreate the merge commits using the
421
`recursive` merge strategy; Different merge strategies can be used only via
422
explicit `exec git merge -s <strategy> [...]` commands.
423
+
407
-See also REBASING MERGES below.
424
+See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
425
426
-p::
427
--preserve-merges::
@@ -415,6 +432,8 @@ See also REBASING MERGES below.
432
This uses the `--interactive` machinery internally, but combining it
433
with the `--interactive` option explicitly is generally not a good
434
idea unless you know what you are doing (see BUGS below).
435
++
436
+See also INCOMPATIBLE OPTIONS below.
437
438
-x <cmd>::
439
--exec <cmd>::
@@ -437,6 +456,8 @@ squash/fixup series.
456
+
457
This uses the `--interactive` machinery internally, but it can be run
458
without an explicit `--interactive`.
459
++
460
+See also INCOMPATIBLE OPTIONS below.
461
462
--root::
463
Rebase all commits reachable from <branch>, instead of
@@ -447,6 +468,8 @@ without an explicit `--interactive`.
468
When used together with both --onto and --preserve-merges,
469
'all' root commits will be rewritten to have <newbase> as parent
470
instead.
471
++
472
+See also INCOMPATIBLE OPTIONS below.
473
474
--autosquash::
475
--no-autosquash::
@@ -461,11 +484,11 @@ without an explicit `--interactive`.
484
too. The recommended way to create fixup/squash commits is by using
485
the `--fixup`/`--squash` options of linkgit:git-commit[1].
486
+
464
-This option is only valid when the `--interactive` option is used.
465
-+
487
If the `--autosquash` option is enabled by default using the
488
configuration variable `rebase.autoSquash`, this option can be
489
used to override and disable this setting.
490
++
491
+See also INCOMPATIBLE OPTIONS below.
492
493
--autostash::
494
--no-autostash::
@@ -487,6 +510,52 @@ recreates the topic branch with fresh commits so it can be remerged
510
successfully without needing to "revert the reversion" (see the
511
link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
512
513
+INCOMPATIBLE OPTIONS
514
+--------------------
515
+
516
+git-rebase has many flags that are incompatible with each other,
517
+predominantly due to the fact that it has three different underlying
518
+implementations:
519
+
520
+ * one based on linkgit:git-am[1] (the default)
521
+ * one based on git-merge-recursive (merge backend)
522
+ * one based on linkgit:git-cherry-pick[1] (interactive backend)
523
+
524
+Flags only understood by the am backend:
525
+
526
+ * --committer-date-is-author-date
527
+ * --ignore-date
528
+ * --whitespace
529
+ * --ignore-whitespace
530
+ * -C
531
+
532
+Flags understood by both merge and interactive backends:
533
+
534
+ * --merge
535
+ * --strategy
536
+ * --strategy-option
537
+ * --allow-empty-message
538
+
539
+Flags only understood by the interactive backend:
540
+
541
+ * --[no-]autosquash
542
+ * --rebase-merges
543
+ * --preserve-merges
544
+ * --interactive
545
+ * --exec
546
+ * --keep-empty
547
+ * --autosquash
548
+ * --edit-todo
549
+ * --root when used in combination with --onto
550
+
551
+Other incompatible flag pairs:
552
+
553
+ * --preserve-merges and --interactive
554
+ * --preserve-merges and --signoff
555
+ * --preserve-merges and --rebase-merges
556
+ * --rebase-merges and --strategy
557
+ * --rebase-merges and --strategy-option
558
+
559
include::merge-strategies.txt[]
560
561
NOTES