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

Christian Couder <chriscool@tuxfamily.org> writes:

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.

As you mentioned in the proposed commit log message of the other entry, you have a different behaviour for unmerged case. Can you add that case to the table as well?

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).