Re: [PATCH] Documentation: make 3-way merge warning more generic

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 1, 2017, 19:26 UTC
Message-ID: <xmqqpogwszdm.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170401133124.10479-1-sandals@crustytoothpaste.net>

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Show 13 quoted lines

>  With the strategies that use 3-way merge (including the default, 'recursive'),
> -if a change is made on both branches, but later reverted on one of the
> -branches, that change will be present in the merged result; some people find
> -this behavior confusing.  It occurs because only the heads and the merge base
> -are considered when performing a merge, not the individual commits.  The merge
> -algorithm therefore considers the reverted change as no change at all, and
> -substitutes the changed version instead.
> +only the heads and the merge base are considered when performing a merge, not
> +the individual commits.  This means that if a change is made on both branches,
> +but later reverted on one of the branches, that change will be present in the
> +merged result; some people find this behavior confusing.  The merge algorithm
> +considers the reverted change as no change at all, and substitutes the changed
> +version instead.

I agree that it makes sense to say 3-way merge considers only three points upfront.

I do not think "this means" is helpful to the readers, though. Drop "This means that" and instead rewrite the remainder of the paragraph after "present in the merged result", perhaps?

	If a change is made on both branches but later reverted on
	one of the branches, the net effect the branch that reverted
	the change has to the project is nothing, while the net
	effect of the other branch is to make that change.  The
	3-way merge, i.e. "if one branch did something while the
	other branch didn't do that something, merge result is to do
	that something", rule keeps the change in the merge result.

We do not need to say "some people find this confusing" buried in a long paragraph, which would not even serve the purpose of attracting readers' eyes by shouting "THIS MAY BE DIFFICULT, PAY ATTENTION". The last sentence in the original (and your version) only repeats the same thing without saying what the real 3-way merge rule is, and I think a rewrite like the above that makes it more explicit is easier to understand.