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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html