reset --merge documentation typo?

reset --merge documentation typo?

[Solomon Ucko]

Oops, accidentally sent as HTML instead of plain text.

The documentation for `git reset --merge` states:

> Resets the index and updates the files in the working tree that are
> different between `<commit>` and `HEAD`, but keeps those which are
> different between the index and working tree (i.e. which have changes
> which have not been added).
> If a file that is different between `<commit>` and the index has
> unstaged changes, reset is aborted.
>
> In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
> but carries forward unmerged index entries.

Where it says "`HEAD`", should it say "the index"?

Thanks,
Solomon Ucko

Re: reset --merge documentation typo?

[Junio C Hamano]

Solomon Ucko <solly.ucko@gmail.com> writes:

> Oops, accidentally sent as HTML instead of plain text.
>
> The documentation for `git reset --merge` states:

It is talknig about `git reset --merge <commit>`.


>> Resets the index and updates the files in the working tree that are
>> different between `<commit>` and `HEAD`, but keeps those which are
>> different between the index and working tree (i.e. which have changes
>> which have not been added).

Correct.  The command makes this request to "git".

    I am on the commit at `HEAD`; I want to move to <commit> as if I
    did "git checkout <otherbranch>", updating the files in the
    working tree to that of <otherbranch> except that if I had local
    changes from `HEAD` for a path, and the path is identical
    between `HEAD` and <otherbranch>, carry my local changes along,
    but I am not flipping to a different branch---instead I am
    resetting the tip of the current branch.

It allows the user to pretend as if the user started making these
local changes _after_ "git reset --hard <commit>", on top of
<commit>, and that is only possible because the command makes sure
that the paths involved in these local changes are the same between
`HEAD` and <commit>.

> Where it says "`HEAD`", should it say "the index"?

No.

Re: reset --merge documentation typo?

[Solomon Ucko]

On Sat, Jun 20, 2020 at 12:59 PM Junio C Hamano <gitster@pobox.com> wrote:
> > The documentation for `git reset --merge` states:
> It is talknig about `git reset --merge <commit>`.

Yep, that's what I meant to say.

>     I am on the commit at `HEAD`; I want to move to <commit> as if I
>     did "git checkout <otherbranch>", updating the files in the
>     working tree to that of <otherbranch> except that if I had local
>     changes from `HEAD` for a path, and the path is identical
>     between `HEAD` and <otherbranch>, carry my local changes along,
>     but I am not flipping to a different branch---instead I am
>     resetting the tip of the current branch.
>
> It allows the user to pretend as if the user started making these
> local changes _after_ "git reset --hard <commit>", on top of
> <commit>, and that is only possible because the command makes sure
> that the paths involved in these local changes are the same between
> `HEAD` and <commit>.

That makes sense, thanks.

> > Where it says "`HEAD`", should it say "the index"?
> No.

I wrote a simple bash script (let me know if I should send it) to test
the behavior of `git reset --merge <commit>`, and got the following
results. I hard-coded the combinations; did I miss any?

    (working tree, index, (HEAD), target commit => resulting working tree)
    AA(A)A => A
    AA(A)B => B
    AA(B)A => A
    AA(B)B => B
    AA(B)C => C
    AB(A)A => abort
    AB(A)B => A
    AB(A)C => abort
    AB(B)A => abort
    AB(B)B => A
    AB(B)C => abort
    AB(C)A => abort
    AB(C)B => A
    AB(C)C => abort
    AB(C)D => abort

It appears that the file contents in HEAD have no effect on the result.

Also, the AB(A)B => A case only seems to make sense with "`HEAD`"
replaced with "the index" in the explanation, since the version in the
working tree matches the version in `HEAD`, but is kept anyways, since
it differs from the index's. Since the index's file matches the target
commit's, the operation is not aborted.

Same thing for the AA(B)B => B and AA(B)C => C cases: the working tree
differs from `HEAD`, so the working tree's version should have been
kept, but instead, since the working tree matches the index, the
target's version is used.

FYI, I'm testing with git version 2.20.1. Was this behavior changed recently?

Solomon Ucko