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

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 30, 2025, 05:23 UTC
Message-ID: <xmqqwm24fsq4.fsf@gitster.g>
In-Reply-To: <d6582dc53ca852ef01421d2dd2c446dadb731dad.1766103827.git.ben.knoble+github@gmail.com>

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

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