git-rebase.txt: add more details about behavioral differences of backends
Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Feb 15, 2020 at 21:36 UTC
be50c938dfc1555ea62df455a41138e41503b952
1 file changed
+80
-5
Documentation/git-rebase.txt
+80
-5
@@ -416,7 +416,7 @@ with `--keep-base` in order to drop those commits from your branch.
416
417
--ignore-whitespace::
418
--whitespace=<option>::
419
- These flag are passed to the 'git apply' program
419
+ These flags are passed to the 'git apply' program
420
(see linkgit:git-apply[1]) that applies the patch.
421
+
422
See also INCOMPATIBLE OPTIONS below.
@@ -563,8 +563,8 @@ The following options:
563
564
* --committer-date-is-author-date
565
* --ignore-date
566
- * --whitespace
566
* --ignore-whitespace
567
+ * --whitespace
568
* -C
569
570
are incompatible with the following options:
@@ -615,9 +615,84 @@ handling commits that become empty.
615
Directory rename detection
616
~~~~~~~~~~~~~~~~~~~~~~~~~~
617
618
-Directory rename heuristics are enabled in the merge and interactive
619
-backends. Due to the lack of accurate tree information, directory
620
-rename detection is disabled in the am backend.
618
+Due to the lack of accurate tree information (arising from
619
+constructing fake ancestors with the limited information available in
620
+patches), directory rename detection is disabled in the am backend.
621
+Disabled directory rename detection means that if one side of history
622
+renames a directory and the other adds new files to the old directory,
623
+then the new files will be left behind in the old directory without
624
+any warning at the time of rebasing that you may want to move these
625
+files into the new directory.
626
+
627
+Directory rename detection works with the merge and interactive
628
+backends to provide you warnings in such cases.
629
+
630
+Context
631
+~~~~~~~
632
+
633
+The am backend works by creating a sequence of patches (by calling
634
+`format-patch` internally), and then applying the patches in sequence
635
+(calling `am` internally). Patches are composed of multiple hunks,
636
+each with line numbers, a context region, and the actual changes. The
637
+line numbers have to be taken with some fuzz, since the other side
638
+will likely have inserted or deleted lines earlier in the file. The
639
+context region is meant to help find how to adjust the line numbers in
640
+order to apply the changes to the right lines. However, if multiple
641
+areas of the code have the same surrounding lines of context, the
642
+wrong one can be picked. There are real-world cases where this has
643
+caused commits to be reapplied incorrectly with no conflicts reported.
644
+Setting diff.context to a larger value may prevent such types of
645
+problems, but increases the chance of spurious conflicts (since it
646
+will require more lines of matching context to apply).
647
+
648
+The interactive backend works with a full copy of each relevant file,
649
+insulating it from these types of problems.
650
+
651
+Labelling of conflicts markers
652
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
653
+
654
+When there are content conflicts, the merge machinery tries to
655
+annotate each side's conflict markers with the commits where the
656
+content came from. Since the am backend drops the original
657
+information about the rebased commits and their parents (and instead
658
+generates new fake commits based off limited information in the
659
+generated patches), those commits cannot be identified; instead it has
660
+to fall back to a commit summary. Also, when merge.conflictStyle is
661
+set to diff3, the am backend will use "constructed merge base" to
662
+label the content from the merge base, and thus provide no information
663
+about the merge base commit whatsoever.
664
+
665
+The interactive backend works with the full commits on both sides of
666
+history and thus has no such limitations.
667
+
668
+Hooks
669
+~~~~~
670
+
671
+The am backend has not traditionally called the post-commit hook,
672
+while the merge/interactive backend has. However, this was by
673
+accident of implementation rather than by design. Both backends
674
+should have the same behavior, though it is not clear which one is
675
+correct.
676
+
677
+Miscellaneous differences
678
+~~~~~~~~~~~~~~~~~~~~~~~~~
679
+
680
+There are a few more behavioral differences that most folks would
681
+probably consider inconsequential but which are mentioned for
682
+completeness:
683
+
684
+* Reflog: The two backends will use different wording when describing
685
+ the changes made in the reflog, though both will make use of the
686
+ word "rebase".
687
+
688
+* Progress, informational, and error messages: The two backends
689
+ provide slightly different progress and informational messages.
690
+ Also, the am backend writes error messages (such as "Your files
691
+ would be overwritten...") to stdout, while the interactive backend
692
+ writes them to stderr.
693
+
694
+* State directories: The two backends keep their state in different
695
+ directories under .git/
696
697
include::merge-strategies.txt[]
698