Re: [PATCH 2/2] Update docs for change of default merge backend

[Derrick Stolee <stolee@gmail.com>]

On 7/31/2021 8:07 PM, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <newren@gmail.com>
...
> 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