Christian Couder <chriscool@xxxxxxxxxxxxx> writes: > This patch adds a DISCUSSION section that contains some tables to > show how the different "git reset" options work depending on the > states of the files in the working tree, the index, HEAD and the > target commit. > > Signed-off-by: Christian Couder <chriscool@xxxxxxxxxxxxx> Much nicer. > Documentation/git-reset.txt | 66 +++++++++++++++++++++++++++++++++++++++++++ > 1 files changed, 66 insertions(+), 0 deletions(-) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 2d27e40..c9044c9 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -67,6 +67,72 @@ linkgit:git-add[1]). > <commit>:: > Commit to make the current HEAD. If not given defaults to HEAD. > > +DISCUSSION > +---------- > + > +The tables below show what happens when running: > + > +---------- > +git reset --option target > +---------- > + > +to reset the HEAD to another commit (`target`) with the different > +reset options depending on the state of the files. Together with these "mechanical definitions", I think the readers would benefit from reading why some are disallowed. > + working index HEAD target working index HEAD > + ---------------------------------------------------- > + A B C D --soft A B D > + --mixed A D D > + --hard D D D > + --merge (disallowed) "reset --merge" is meant to be used when resetting out of a conflicted merge. Because 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, the fact that we see difference between the index and the HEAD and also between the index and the work tree means that we are not seeing a state that a mergy operation left after failing with a conflict. That is why we disallow --merge option in this case, and the next one. > + working index HEAD target working index HEAD > + ---------------------------------------------------- > + A B C C --soft A B C > + --mixed A C C > + --hard C C C > + --merge (disallowed) The same as above, but you are resetting to the same commit. > + working index HEAD target working index HEAD > + ---------------------------------------------------- > + B B C D --soft B B D > + --mixed B D D > + --hard D D D > + --merge D D D > + working index HEAD target working index HEAD > + ---------------------------------------------------- > + B B C C --soft B B C > + --mixed B C C > + --hard C C C > + --merge C C C As this table is not only about "--merge" but to explain "reset", I think other interesting cases should also be covered. w=A i=B H=B t=B This is "we had local change in the work tree that was unrelated to the merge", and "reset --merge" should be a no-op for this path. w=A i=B H=B t=C This "reset --merge" is like "using checkout to switch to a commit that has C but we have changes in the work tree", and should fail just like "checkout branch" in such a situation fails without "-m" option. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html