Re: [PATCH v6 2/4] Documentation: reset: add some tables to describe the different options

[Junio C Hamano <gitster@pobox.com>]

Christian Couder <chriscool@tuxfamily.org> 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@tuxfamily.org>

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.