Re: [PATCH 09/10] Documentation: add coverage of the `ort` merge strategy

On Tue, Aug 3, 2021 at 5:04 PM Johannes Schindelin
[off-list ref] wrote:

Hi Elijah,

On Tue, 3 Aug 2021, Elijah Newren via GitGitGadget wrote:

quoted

From: Elijah Newren <redacted>

Signed-off-by: Elijah Newren <redacted>
---
 Documentation/git-rebase.txt       |  7 ++++---
 Documentation/merge-strategies.txt | 14 ++++++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index b4429954480..3e112011c6f 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt

@@ -340,9 +340,10 @@ See also INCOMPATIBLE OPTIONS below.

 -m::
 --merge::
-     Use merging strategies to rebase.  When the recursive (default) merge
-     strategy is used, this allows rebase to be aware of renames on the
-     upstream side.  This is the default.
+     Use merging strategies to rebase.  When either the `recursive`
+     (default) or `ort` merge strategy is used, this allows rebase
+     to be aware of renames on the upstream side.  This is the
+     default.

Since this now talks about two merge strategies, I think "This is the
default" needs to specify which of the two strategies is the default.

It does, but I agree the wording is a bit confusing.  "This is the
default" refers to the fact that "Using merging strategies to rebase"
is the default (as opposed to using git-am).  We can then list some of
the possible merge strategies and which are the default (which we did
in the second sentence).  However, diving into a discussion about
individual strategies might be out of place here.  It looks like that
was originally mentioned because that allowed rebase to handle
renames, but git-am -3 gained that ability well over a decade ago via
falling back to the merge machinery.  So perhaps we should just
simplify this to:

"""
Using merging strategies to rebase (this is the default since Git
v2.26.0).  Note that there are multiple merge strategies available,
and specific ones can be picked with the `--strategy` option.
"""

quoted

 +
 Note that a rebase merge works by replaying each commit from the working
 branch on top of the <upstream> branch.  Because of this, when a merge

diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index d21dbd1e051..d13d4a29875 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt

@@ -96,6 +96,20 @@ subtree[=<path>];;
      is prefixed (or stripped from the beginning) to make the shape of
      two trees to match.

+ort::
+     This is meant as a drop-in replacement for the `recursive`
+     algorithm (as reflected in its acronym -- "Ostensibly
+     Recursive's Twin"), and will likely replace it in the future.
+     It fixes corner cases that the `recursive` strategy handles
+     suboptimally, and is significantly faster in large
+     repositories -- especially when many renames are involved.
++
+The `ort` strategy takes all the same options as `recursive`.
+However, it ignores three of those options: `no-renames`,
+`patience` and `diff-algorithm`.  It always runs with rename
+detection (it handles it much faster than `recursive` does), and
+it specifically uses diff-algorithm=histogram.

Probably `diff-algorithm=histogram` should also be enclosed within
backticks.

I'll fix that up.