Re: [PATCH 6/6] Documentation: tweak How Merge Works

From: Thomas Rast <trast@student.ethz.ch>
Date: Jan 11, 2010, 23:11 UTC
Message-ID: <201001120011.42654.trast@student.ethz.ch>
In-Reply-To: <20100111084355.GF23806@progeny.tock>

The below and earlier comments aside, I really like this series. It seems to make the manpage much more accessible.

Jonathan Nieder wrote:

Show 11 quoted lines

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index ec9c6d3..7ae0f65 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -96,62 +96,56 @@ merge commit.
>  
>  This behavior can be suppressed with the `--no-ff` option.
>  
> -include::merge-strategies.txt[]
> -
> -

I'm not sure whether you deliberately did this, or deliberately deferred it to this patch, but this "sneak moves" the merge-strategies section beyond "TRUE MERGE" (was "HOW MERGE WORKS").

So the section layout changes as follows when comparing current master with your series:

 NAME
 SYNOPSIS
 DESCRIPTION
 OPTIONS
+PRE-MERGE CHECKS
+FAST-FORWARD MERGE
+TRUE MERGE
 MERGE STRATEGIES
-CONFIGURATION
-HOW MERGE WORKS
 HOW CONFLICTS ARE PRESENTED
 HOW TO RESOLVE CONFLICTS
 EXAMPLES
+CONFIGURATION
 SEE ALSO
 AUTHOR
 DOCUMENTATION
 GIT
 NOTES

While I agree with the general intent of deferring the strategies further back, wouldn't it be better go all the way and instead put them before (or even after, but one of them uses -s ours) "EXAMPLES"? The average user will care more about conflicts than about strategies other than 'recursive'.

Show 5 quoted lines

> +1. A version reconciling the changes from all branches to be
> +   merged is written to the index file and your working tree;
> +2. The index file is written out as a tree;
>  3. The tree gets committed; and
>  4. The `HEAD` pointer gets advanced.

Could we do away with the detail here? The user most likely does not care about the exact order because he cannot "see" it happening anyway. So how about

  A merged version reconciling the changes from all branches to be
  merged is committed, and your HEAD, index, and working tree are
  updated to it.  (It is possible to have modifications in the working
  tree as long as they do not overlap; the update will preserve them.)

and then snip everything up to

> +When it is not obvious how to reconcile the changes, the following
> +happens:

because that is far more important to the user: he is left in the middle of the described state.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch