Re: [PATCH v2 3/4] reset: add option "--merge-safe" to "git reset"

> Christian Couder <chriscool@tuxfamily.org> writes:
> > From: Stephan Beyer <s-beyer@gmx.net>
> >
> > This option is nearly like "--merge" except that it is
> > safer. The table below show the differences between these
> > options.
> >
> > working index HEAD target         working index HEAD
> >   B      B     A     A   --m-s      B      A     A
> >                          --merge    A      A     A
> >   B      B     A     C   --m-s       (disallowed)
> >                          --merge    C      C     C
> >
> > In this table, A, B and C are some different states of
> > a file. For example the first 2 lines of the table mean
> > that if a file is in state B in the working tree and
> > the index, and in a different state A in HEAD and in
> > the target, then "git reset --merge-safe target" will
> > put the file in state B in the working tree and in
> > state A in the index and HEAD.
>
> At first, I had to spend a few minutes guessing what you meant by
> "target" in the table.  All the other words are well known and do not
> need to be explained, but you can make it even easier to understand by
> updating the sentence before the table, perhaps like:
>
>     When running "git reset --option target" to reset the HEAD to another
>     commit (as a special case "target" could be the same as HEAD), here
>     is what happens to paths in various state.

> The original use case of Linus's "reset --merge" was:
>
>     $ edit ... ;# you may have some local changes to the work tree
>     $ git merge/pull ...
>     ... (1) it merges cleanly;
>     ... (2) you see conflicts and do not commit, or
>     ... (3) you resolve conflicts and commit, while leaving the earlier
>     ...     modified paths alone.
>     ... In any of the three cases, you inspect the result, and say
>     ... "ah, crap!"
>     ... You want to go back to the state before the merge, i.e.
>     ... target = HEAD^ in (1) or (3) above and target = HEAD in (2).
>     $ git reset --merge $target

> Recall that "git merge/pull ..." step does not even touch anything if you
> have a dirty index (i.e. "diff --cached" is non-empty), so any difference
> between the index and HEAD to reset the failed merge away must come from
> the merge itself
>
> Immediately before you run "reset --merge" in the above sequence, you can
> categorize the paths in various states this way:
>
>   work   index  HEAD  how that path got into this state...
>     A      A     A    not involved in this merge.
>     B      A     A    not involved in this merge, originally modified.
>     B      B     A    cleanly merged.
>     B      B     B    cleanly merged (and committed if (1) or (3)).
>     C      U     A    merge left conflicts
>
> where U denotes unmerged path in the index, and C is a file in the work
> tree with conflict markers.  The path had content A in HEAD before the
> start of the merge that you are resetting away.
>
> Note that the target is A in all cases in the above table.
>
> We would want to go back to HEAD == index == target for all of these
> cases, and discarding B in "cleanly merged" entries is absolutely the
> right thing to do.  Clearly, --merge-safe is _not_ designed to work in
> this scenario.

> Don't get me wrong.  I am not saying --merge-safe is unsafe nor useless.
>
> I am trying to show a way with an intended use-case (and the mechanical
> notation you and Daniel wrote up, which is very nice to illustrate what
> exactly happens) to explain how --merge works, and more importantly why
> it works that way.
>
> That is because I would like to see an intended use case of this new
> feature in a bigger picture.  With the table, I can see what it does (or
> at least what you wanted it to do), but it does not clearly explain what
> this new mode of operation is good for, in what context it is designed
> to be used, and what problem it intends to solve.  I think you find it
> very clear, by reading my explanation above, what Linus's --merge is
> intended to solve:
>
> 	After a (possibly conflicted) merge modified my index and my work
>         tree, "reset --hard" to the commit before I started the merge
> will discard the local modifications I had in the work tree before the
> merge.  "reset --merge" was invented to let me go back to the state
> before the merge, without discarding such local changes I had before the
> merge.
>
> I want to be able to explain to others what --merge-safe is for in a
> similar way myself before I have it in my tree, and I can't (yet).