Re: [PATCH 2/6] Documentation: merge: add an overview

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> The reader unfamiliar with the concepts of branching and merging
> would have been completely lost.  Try to help him with a diagram.

Good idea.

>  DESCRIPTION
>  -----------
> -This is the top-level interface to the merge machinery
> -which drives multiple merge strategy scripts.
> +Incorporates changes leading up to the named commits into the
> +current branch.

Having "since the histories diverged" somewhere in this first sentence
would clarify the concepts better, I think.

> +Assume the following history exists and the current branch is
> +"`master`":
> +
> +------------
> +          A---B---C topic
> +         /
> +    D---E---F---G master
> +------------
> +
> +Then "`git merge topic`" will apply the changes from `A`, `B`,
> +and `C` to the work tree, and if they do not conflict with any
> +changes from `master`, will store the result in a new commit along
> +with the names of the two parent commits and a log message from the
> +user describing the changes.

 - Don't spell A, B and C out; technically we don't do that, and
   conceptually "changes since E until C" is exactly the same.

 - Don't talk about "what it does" first, but talk about "what it is used
   for" iow "why do you want to use it".

 - "What it is used for" doesn't have to talk about "if it does not
   conflict" yet; it is merely a lower-level detail that the main part of
   the document can teach the users to help the tool achieve its goal
   (i.e. "what it is used for") when it cannot do so automatically.

	`git merge topic` is used to replay the change the topic has made
        since it diverged from master's history (i.e. E) until its current
        commit (i.e. C) on top of master, and store the result in a new
        commit along with....

> +------------
> +          A---B---C topic
> +         /         \
> +    D---E---F---G---H master
> +------------
>  
>  The second syntax (<msg> `HEAD` <remote>) is supported for
>  historical reasons.  Do not use it from the command line or in
> -- 
> 1.6.6