Re: [PATCH 2/2] user-manual: Document that "git merge" doesn't like uncommited changes.

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

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> We explain the user why uncommited changes can be problematic with merge,
> and point to "commit" and "stash" for the solution.

It is a shame that our existing documentation did not address this, and
the patch certainly takes us in the right direction.

I haven't seen a clear description of distinction between two vastly
different modes of failure from "git merge"---one that stops before even
touching anything, and one that results in conflicts to be resolved---and
how to tell them apart.  As the course of action after these two modes are
quite different, it helps users to teach it early.

I attempted to summarize it some time ago:

    http://gitster.livejournal.com/25801.html
    (Completing a merge)

    http://gitster.livejournal.com/29060.html
    (Fun with keeping local changes around)

I am not very satisfied with them, but it might be a good start.

>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/user-manual.txt |   14 +++++++++++---
>  1 files changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 269ec47..6b4a037 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1176,14 +1176,22 @@ How to merge
>  ------------
>  
>  You can rejoin two diverging branches of development using
> -linkgit:git-merge[1]:
> +linkgit:git-merge[1].
>  
>  -------------------------------------------------
>  $ git merge branchname
>  -------------------------------------------------
>  
>  merges the development in the branch "branchname" into the current
> -branch.  If there are conflicts--for example, if the same file is
> +branch.  Note that Git merges committed changes, but not the working
> +tree itself.  Therefore, if you have uncommitted changes touching the
> +same files as the ones impacted by the merge, Git will refuse to
> +proceed.

"but not the working tree itself" is not incorrect per-se, but misses the
point.  How about...

	A merge is made by combining the changes made in "branchname" and
        the changes made up to the latest commit in your current branch
        since their histories forke.  The work tree is overwritten by the
        result of the merge when this combining is done cleanly, or
        overwritten by a half-merged results when this combining results
        in conflicts.  Therefore, ...

> +proceed.  Most of the time, you will want to commit your changes before
> +you can merge, and if you don't, then linkgit:git-stash[1] can take
> +these changes away while you're doing the merge, and reapply them
> +afterwards.
> +
> +If there are conflicts--for example, if the same file is
>  modified in two different ways in the remote branch and the local
>  branch--then you are warned; the output may look something like this:
>  
> @@ -1679,7 +1687,7 @@ Sharing development with others
>  Getting updates with git pull
>  -----------------------------
>  
> -After you clone a repository and make a few changes of your own, you
> +After you clone a repository and commit a few changes of your own, you
>  may wish to check the original repository for updates and merge them
>  into your own work.
>  
> -- 
> 1.6.5.3.435.g5f2e3.dirty