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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 17, 2025, 23:25 UTC
Message-ID: <xmqqa51pxg9p.fsf@gitster.g>
In-Reply-To: <0be166483f547de866744917e6cb19eed13a8088.1760731558.git.gitgitgadget@gmail.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.

Show 13 quoted lines

>  `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.