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

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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +`git reset` only modifies the index: use linkgit:git-restore[1] instead
> +if you'd like to also update the file in your working directory.

I cannot judge if it is clear enough with the above sentence that we
are only talking about "the other forms", but if that is the case
and it is clear we are not talking about the mode where the command
repoints HEAD to another commit, the above is a good piece of advice.

If not, perhaps

    When specified what paths to modify, `git reset` updates only
    the index (without updating the HEAD or working tree files).  If
    you want to update the files as well as the index entries, use
    git-restore.

may be a way to clarify the distinction between two modes.

>  `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 unstaged.
>  +
>  This means that `git reset -p` is the opposite of `git add -p`, i.e.
> -you can use it to selectively reset hunks. See the "Interactive Mode"
> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
> +you can use it to selectively unstage changes. See the "Interactive Mode"
> +section of linkgit:git-add[1] to learn how to use the `--patch` option.

I do not see a good reason why we avoid saying the noun "patch",
especially when we see it in the option.  If we were allowed to say
"patch" here, "changes from the difference between ..." can be
rephrased to "parts of the patch that makes the index match the
specified commit", which may be simpler.

Also "unstaged" is only true when <tree-ish> is "HEAD".  If you are
grabbing the contents recorded in a different commit and shoving
them into the index, that is not "unstaging" at all.  Rather, if you
are planning to make a commit out of the index after doing so, that
is rather "staging" a change!  While the verb "to (un)stage" may
have been a useful tool to explain the act of updating index entries
to describe its effect relative to what is in HEAD, in this
particular case, it is probably more confusing than illuninating to
use it.