Re: [PATCH 09/13] Improve section "Merge multiple trees"

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Aug 25, 2013, 05:23 UTC
Message-ID: <20130825052327.GK2882@elie.Belkin>
In-Reply-To: <1473018875.1091101.1377329545934.JavaMail.ngmail@webmail08.arcor-online.net>

Thomas Ackermann wrote:

Show 8 quoted lines

> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3992,16 +3992,16 @@ Merging multiple trees
>  
>  Git helps you do a three-way merge, which you can expand to n-way by
>  repeating the merge procedure arbitrary times until you finally
> -"commit" the state.
> +commit the state.

The above sentence is unclear to me both before and after this change.

Git helps me do a three-way merge, but I'm on my own if I want to expand to n-way? Those times I repeat it are arbitrary times, not arbitrarily many times? Using "git merge" I make commits, but I do not finally commit to the result until the (n-1)st? And what is this state I am committing?

Maybe the intent is

	Git can help you perform a three-way merge, which can in turn be
	used for a many-way merge by repeating the merge procedure several
	times.  The usual situation is that you only do one three-way merge
	(reconciling two lines of history) and commit the result, but if
	you like to, you can merge several branches in one go.

	To perform a three-way merge, you start with the two commits you
	want to merge, find their closest common parent (a third commit),
	and compare the trees corresponding to these three commits.

	To get the "base" for the merge, look up the common parent of two
	commits:

		$ git merge-base <commit1> <commit2>

	This prints the name of a commit they are both based on.
	...

[...]

> -To get the "base" for the merge, you first look up the common parent
> +To get the base for the merge, you first look up the common parent

Merge base hasn't been defined, so this is using quotes to point out that it is defining a new, unfamiliar term.

[...]

> -now look up the "tree" objects of those commits, which you can easily
> -do with (for example)
> +now look up the tree objects of those commits, which you can easily
> +do with

Yes.