git reset --merge documentation improvments

git reset --merge documentation improvments

[Philippe Vaucher]

Hello,

The current documentation for --merge is:

"Resets the index [1] and updates the files in the working tree that
are different between <commit> and HEAD, but keeps those which are
different between the index [2] and working tree"

I think this is confusing, because [1] is the *after-reset* index and
[2] is the *before-reset* index. If you fail to realise this it looks
like this "resets index (so index is empty) and then updates worktree
but skip files staged from index" --> "but there's nothing staged, the
index was reset!"

I think a better sentence would be:

"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, and finally resets the index."

Or something along those lines.

Philippe

Re: git reset --merge documentation improvments

[Vincent van Ravesteijn]

Op 23-11-2011 9:31, Philippe Vaucher schreef:
> Hello,
>
> The current documentation for --merge is:
>
> "Resets the index [1] and updates the files in the working tree that
> are different between<commit>  and HEAD, but keeps those which are
> different between the index [2] and working tree"
>
> I think this is confusing, because [1] is the *after-reset* index and
> [2] is the *before-reset* index.

You mean that you read that the *after-reset* index is reset ? They both 
refer to the *before-reset* index.

>   If you fail to realise this it looks
> like this "resets index (so index is empty) and then updates worktree
> but skip files staged from index" -->  "but there's nothing staged, the
> index was reset!"

The misunderstanding comes from the added "then".

>
> I think a better sentence would be:
>
> "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, and finally resets the index."

There is nothing to update as long as the index is not reset.

Vincent

Re: git reset --merge documentation improvments

[Philippe Vaucher]

>> "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, and finally resets the index."
>
> There is nothing to update as long as the index is not reset.

Well then I simply don't understand what --merge does. Is it like
--keep but instead of failing when a file-to-be-overwritten has
changes it simply ignores the overwriting and continues?

Philippe