From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 04 Aug 2021 00:19:41 GMT
Subject: Re: [PATCH 04/10] merge-strategies.txt: update wording for the resolve strategy
Message-ID: <xmqqmtpyrrhe.fsf@gitster.g>
In-Reply-To: <3989f194ba91e64852285064b652979861445c03.1628004920.git.gitgitgadget@gmail.com>

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@gmail.com>
>
> The resolve merge strategy was given prominent positioning in this
> document, being listed first since it was the default at the time the
> document was written.  It hasn't been the default since before Git v1.0
> was released, though.  Move it later in the document, near `octopus` and
> `ours`.

I think it was listed first because it was written first.

> Further, the wording for "resolve" claimed that it was "considered
> generally safe and fast", which implies that the other strategies are
> not.

I do not think it never implied any such thing; it is good to remove
it, or add the same to all strategies, though.

> diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
> index 5d707e952aa..6b6017e1cc8 100644
> --- a/Documentation/merge-strategies.txt
> +++ b/Documentation/merge-strategies.txt
> @@ -6,13 +6,6 @@ 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
> @@ -106,6 +99,13 @@ subtree[=<path>];;
>  	is prefixed (or stripped from the beginning) to make the shape of
>  	two trees to match.
>  
> +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.  It cannot handle renames.  This was
> +	the default merge algorithm prior to November 2005.

"It does not handle renames"; it wasn't like we wanted to do so and
cannot---we didn't want to, didn't think it was worth doing, it was
not part of the design objective to do renames, period.

I do not think it is even worth mentioning that it was the default
in the past.  And I do not think it is worth saying what timeframe
the recursive was the default, either.

>  octopus::
>  	This resolves cases with more than two heads, but refuses to do
>  	a complex merge that needs manual resolution.  It is