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

[Thomas Rast <trast@student.ethz.ch>]

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

Jonathan Nieder wrote:
> 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'.

> +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