On 7/31/2021 8:07 PM, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <newren@xxxxxxxxx>
...
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index afdaeab8503..072bf84fa8a 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -275,7 +275,7 @@ best to always use a regular merge commit.
>
> [[merge-two-revert-one]]
> If I make a change on two branches but revert it on one, why does the merge of those branches include the change?::
> - By default, when Git does a merge, it uses a strategy called the recursive
> + By default, when Git does a merge, it uses a strategy called the ort
> strategy, which does a fancy three-way merge. In such a case, when Git
nit: I feel like quotes around "ort" would be beneficial here. It would have
also helped the previous version, too, in my opinion.
> performs the merge, it considers exactly three points: the two heads and a
> third point, called the _merge base_, which is usually the common ancestor of
> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index eb0aabd396f..72b53188504 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -112,8 +112,8 @@ With --squash, --commit is not allowed, and will fail.
> Use the given merge strategy; can be supplied more than
> once to specify them in the order they should be tried.
> If there is no `-s` option, a built-in list of strategies
> - is used instead ('git merge-recursive' when merging a single
> - head, 'git merge-octopus' otherwise).
> + is used instead (`ort` when merging a single head,
> + `octopus` otherwise).
>
> -X <option>::
> --strategy-option=<option>::
> diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
> index 2912de706bf..6caf3fd6486 100644
> --- a/Documentation/merge-strategies.txt
> +++ b/Documentation/merge-strategies.txt
> @@ -6,28 +6,23 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies
> can also take their own options, which can be passed by giving `-X<option>`
> arguments to `git merge` and/or `git pull`.
>
> -resolve::
> - This can only resolve two heads (i.e. the current branch
> - and another branch you pulled from) using a 3-way merge
> - algorithm. It tries to carefully detect criss-cross
> - merge ambiguities and is considered generally safe and
> - fast.
> -
> -recursive::
> - This can only resolve two heads using a 3-way merge
> - algorithm. When there is more than one common
> - ancestor that can be used for 3-way merge, it creates a
> - merged tree of the common ancestors and uses that as
> - the reference tree for the 3-way merge. This has been
> - reported to result in fewer merge conflicts without
> - causing mismerges by tests done on actual merge commits
> - taken from Linux 2.6 kernel development history.
> - Additionally this can detect and handle merges involving
> - renames, but currently cannot make use of detected
> - copies. This is the default merge strategy when pulling
> - or merging one branch.
> +ort::
> + This is the default merge strategy when pulling or merging one
> + branch. This strategy can only resolve two heads using a
> + 3-way merge algorithm. When there is more than one common
> + ancestor that can be used for 3-way merge, it creates a merged
> + tree of the common ancestors and uses that as the reference
> + tree for the 3-way merge. This has been reported to result in
> + fewer merge conflicts without causing mismerges by tests done
> + on actual merge commits taken from Linux 2.6 kernel
> + development history. Additionally this strategy can detect
> + and handle merges involving renames. It does not make use of
> + detected copies. The name for this algorithm is an acronym
> + ("Ostensibly Recursive's Twin") and came from the fact that it
> + was written as a replacement for the previous default
> + algorithm, recursive.
nit: Quotes around "recursive" might be useful here, too.
> +
> -The 'recursive' strategy can take the following options:
> +The 'ort' strategy can take the following options:
(Like these quotes.)
Other than my nits, these doc updates are solid.
Thanks,
-Stolee
