[PATCH] Documentation: reset: add some missing tables

[PATCH] Documentation: reset: add some missing tables

[Christian Couder]

and while at it also explain why --merge option is disallowed in some
cases.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/git-reset.txt |   35 +++++++++++++++++++++++++++++------
 1 files changed, 29 insertions(+), 6 deletions(-)

I must say that I find it a bit strange (and difficult to explain) that
we have:

      working index HEAD target         working index HEAD
      ----------------------------------------------------
       B       C     C    C     --merge   B       C     C

while in the other cases, when it is allowed, --merge is like --hard.

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index dc73dca..1f35278 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -79,6 +79,13 @@ git reset --option target
 to reset the HEAD to another commit (`target`) with the different
 reset options depending on the state of the files.
 
+In these tables, A, B, C and D are some different states of a
+file. For example, the first line of the first table means that if a
+file is in state A in the working tree, in state B in the index, in
+state C in HEAD and in state D in the target, then "git reset --soft
+target" will put the file in state A in the working tree, in state B
+in the index and in state D in HEAD.
+
       working index HEAD target         working index HEAD
       ----------------------------------------------------
        A       B     C    D     --soft   A       B     D
@@ -107,12 +114,28 @@ reset options depending on the state of the files.
 				--hard   C       C     C
 				--merge  C       C     C
 
-In these tables, A, B, C and D are some different states of a
-file. For example, the last line of the last table means that if a
-file is in state B in the working tree and the index, and in a
-different state C in HEAD and in the target, then "git reset
---merge target" will put the file in state C in the working tree,
-in the index and in HEAD.
+      working index HEAD target         working index HEAD
+      ----------------------------------------------------
+       B       C     C    D     --soft   B       C     D
+                                --mixed  B       D     D
+                                --hard   D       D     D
+                                --merge (disallowed)
+
+      working index HEAD target         working index HEAD
+      ----------------------------------------------------
+       B       C     C    C     --soft   B       C     C
+                                --mixed  B       C     C
+                                --hard   C       C     C
+                                --merge  B       C     C
+
+"reset --merge" is meant to be used when resetting out of a conflicted
+merge. Any mergy operation guarantees that the work tree file that is
+involved in the merge does not have local change wrt the index before
+it starts, and that it writes the result out to the work tree. So if
+we see some difference between the index and the target and also
+between the index and the work tree, then it means that we are not
+resetting out from a state that a mergy operation left after failing
+with a conflict. That is why we disallow --merge option in this case.
 
 The following tables show what happens when there are unmerged
 entries:
-- 
1.6.6.rc2.5.g49666

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

[Junio C Hamano]

Christian Couder <chriscool@tuxfamily.org> writes:

> and while at it also explain why --merge option is disallowed in some
> cases.
>
> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> ---
>  Documentation/git-reset.txt |   35 +++++++++++++++++++++++++++++------
>  1 files changed, 29 insertions(+), 6 deletions(-)
>
> I must say that I find it a bit strange (and difficult to explain) that
> we have:
>
>       working index HEAD target         working index HEAD
>       ----------------------------------------------------
>        B       C     C    C     --merge   B       C     C
>
> while in the other cases, when it is allowed, --merge is like --hard.

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.

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

[Christian Couder]

On mardi 05 janvier 2010, Junio C Hamano wrote:
> Christian Couder <chriscool@tuxfamily.org> writes:
> > and while at it also explain why --merge option is disallowed in some
> > cases.
> >
> > Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> > ---
> >  Documentation/git-reset.txt |   35 +++++++++++++++++++++++++++++------
> >  1 files changed, 29 insertions(+), 6 deletions(-)
> >
> > I must say that I find it a bit strange (and difficult to explain) that
> > we have:
> >
> >       working index HEAD target         working index HEAD
> >       ----------------------------------------------------
> >        B       C     C    C     --merge   B       C     C
> >
> > while in the other cases, when it is allowed, --merge is like --hard.
>
> 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.

Thanks for your explanations.
Christian.