Re: [PATCH v2 4/4] doc: git-reset: clarify `git reset <pathspec>`

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

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

>  `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
> -	Interactively select hunks in the difference between the index
> -	and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
> -	in reverse to the index.
> +	Interactively select changes from the difference between the index
> +	and the specified commit or tree (which defaults to `HEAD`).
> +	The chosen changes are added to the index.

The previous iteration said "changes are unstaged", implying that
the changes are removed from the index.  But now it says the changes
are added to the index.  Which one?

I think neither is correct.  I wasn't involved in the design of the
behaviour of "reset -p", but IIUC,

    git reset -p
    git reset -p HEAD

show "git diff --cached HEAD" (i.e., what damage you will cause if
you commit what is in the index), so chosen hunks will be reverted
out of the index if you say "y" to "reset -p" prompt.

On the other hand, 

    git reset -p COMMIT

for COMMIT that is not HEAD gives "git diff -R --cached COMMIT"
(i.e., the changes to take you closer to the named commit), so
chosen hunks will participate in the next commit if you commit after
completing this "reset -p" session.

    The contents in the index are modified using the chosen hunks.

is the best description I can come up with.

The actual prompt asks "unstage this hunk?" when operating against
HEAD, while the prompt changes to "apply this hunk to index?" when
opeating against a commit that is not HEAD, so it might be simpler
not to say anything about the direction of the application (i.e.,
how the chosen hunks are used to modify the index) in this
paragraph, like the above example, may be a viable option.