Re: [PATCH] Documentation: reset: add some missing tables

Christian Couder <chriscool@tuxfamily.org> writes:

That is probably because you don't explain what --merge option is _for_ well enough to your readers. If the reader understands it is to reset away a half-merged conflicted result, starting from a potentially dirty work tree, then it would be very obvious that the above is the right thing to do.

As a prerequisite, the reader should be aware (otherwise they should read some introductory git books, or http://gitster.livejournal.com/29060.html) that a mergy operation can stop without completing a merge in two ways:

 - If a path that is involved in a mergy operation has local changes in
   the work tree, or if the index is dirty, the operation stops _without_
   doing anything.

 - If all paths that are involved in a mergy operation are clean in the
   work tree, the operation is attempted.  If a conflict happens at the
   content level, the operation leaves the paths in conflicted state in
   the index and leaves the conflict markers in the files in the work
   tree.  Be _very_ aware that even in this case, cleanly automerged paths
   are updated in the index and the work tree.

In the first case, you do not have to run "reset --merge", as nothing was done by the mergy operation (it happens to be safe to "reset --merge", as the only thing you lose is a partial add, which you can easily redo from the files in the working tree).

In the latter case, there are four classes of paths:

 (1) Ones that are not involved in the merge at all, and were clean from
     the beginning.  The work tree file, the index and the HEAD would
     match.

     w=C i=C H=C

 (2) Ones that are not involved in the merge at all, but were dirty when
     you started the mergy operation.  They have your local changes in the
     work tree that you wanted to keep across the mergy operation.

     w=B i=C H=C

 (3) Ones that are involved in the merge, and were cleanly merged.  By
     definition, these paths did _not_ have local changes in the work tree
     (otherwise the mergy operation would have stopped without doing
     anything).  These are updated in the index and the files in the work
     tree matches the index after the mergy operation stops.

     w=B i=B H=C

 (4) Ones that are involved in the merge, and were conflicted.  Again, by
     definition, these paths did _not_ have local changes in the work tree
     These are left in the index as conflicted, and the files in the work
     tree have conflict markers after the mergy operation stops.

     w=X i=U H=C

"reset --merge HEAD" is about going back to the state before you started this mergy operation. You don't need to do anything to paths in (1), and you want to reset paths in (3) and (4) back to the HEAD.

Think what you want to do to (2). By definition, they weren't involved in the mergy operation (otherwise you couldn't have come this far), so the difference between the index and the work tree is purely your local changes, untouched by the mergy operation, and have not even been updated in "cvs update" style. The right thing to do is simply leave them as they are.

    Side note.  Explained in the opposite way, if the work tree file is
    different from the index and the index is not unmerged, the difference
    _only_ could have come from the local change before you started your
    mergy operation.  Any other change to the work tree files done by any
    mergy operation will be matched to the index.  So w=B i=C in (2) will
    immediately tell you that the change is a local one that is unrelated
    to the merge.

By the way, people often say that the index is good because it allows you to make partial commits (i.e. "add -p"), but at the same time have this mistaken notion that it is the _primary_ benefit of the index. Actually, a lot more important benefit of the index is (3) above. When you are dealing with a large merge with many paths, often a lot of them automerge cleanly while some gives you conflicts. The automerged results are added to the index and you do not have to see them in "git diff" (as their files and the index match), to allow you concentrate on the conflicted ones very easily.