[PATCH 0/4] doc: git-reset: clarify DESCRIPTION section

[PATCH 0/4] doc: git-reset: clarify DESCRIPTION section

[Julia Evans via GitGitGadget]

I got feedback from 24 Git users about the current git reset man page, using
this tool: https://text-feedback.wizardzines.com/git-reset.

My main goals here are to highlight the git reset [--soft | --hard |
--mixed...] <commit> use of git reset that many users commenting said they
considered the "main" use (which is currently at the end), explain how
--soft, --hard and --mixed work more clearly, and to avoid using terminology
that users don't understand when that's realistic.

Like we discussed with git checkout, there's some tension about using the
word "index" since on one hand many users don't know what it means, but on
the other hand (especially with commands like git reset --hard) it gets very
awkward to talk about what's going on precisely without using that word,
since the index is a core concept in Git's data model. I've done my best
here to use the word "index" where I think it's appropriate and use the word
"staged" otherwise.

There were also quite a few comments about the EXAMPLES section which I
think could also be made clearer, but I'll defer that to a separate patch
series to keep the size of this one under control.

Julia Evans (4):
  doc: git-reset: reorder the forms
  doc: git-reset: clarify intro
  doc: git-reset: clarify `git reset [mode]`
  doc: git-reset: clarify `git reset <pathspec>`

 Documentation/git-reset.adoc | 102 +++++++++++++++++------------------
 1 file changed, 51 insertions(+), 51 deletions(-)


base-commit: a483264b01b977f3e65a4419103c21e6af7412a2
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1991%2Fjvns%2Fclarify-reset-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1991/jvns/clarify-reset-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1991
-- 
gitgitgadget

[PATCH 1/4] doc: git-reset: reorder the forms

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]`
form is the one that they primarily use, and that they were suprised to
see it listed last.
("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what
"Reset current HEAD to the specified state" at the beginning refers
to, and because the `git reset [mode]` form is the only thing that
`git reset` uniquely does, the others could also be done with
`git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 3b9ba9aee9..9843682e81 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
 SYNOPSIS
 --------
 [synopsis]
+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
 git reset [-q] [<tree-ish>] [--] <pathspec>...
 git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
 git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
 
 DESCRIPTION
 -----------
-In the first three forms, copy entries from _<tree-ish>_ to the index.
-In the last form, set the current branch head (`HEAD`) to _<commit>_,
+In the first form, set the current branch head (`HEAD`) to _<commit>_,
 optionally modifying index and working tree to match.
 The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
-
-`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
-`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
-	These forms reset the index entries for all paths that match the
-	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
-	the working tree or the current branch.)
-+
-This means that `git reset <pathspec>` is the opposite of `git add
-<pathspec>`. This command is equivalent to
-`git restore [--source=<tree-ish>] --staged <pathspec>...`.
-+
-After running `git reset <pathspec>` to update the index entry, you can
-use linkgit:git-restore[1] to check the contents out of the index to
-the working tree. Alternatively, using linkgit:git-restore[1]
-and specifying a commit with `--source`, you
-can copy the contents of a path out of a commit to the index and to the
-working tree in one go.
-
-`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.
-+
-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.
+In the last three forms, copy entries from _<tree-ish>_ to the index.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and
@@ -98,6 +72,32 @@ but carries forward unmerged index entries.
 	the submodules' `HEAD` to be detached at that commit.
 --
 
+`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
+`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
+	These forms reset the index entries for all paths that match the
+	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
+	the working tree or the current branch.)
++
+This means that `git reset <pathspec>` is the opposite of `git add
+<pathspec>`. This command is equivalent to
+`git restore [--source=<tree-ish>] --staged <pathspec>...`.
++
+After running `git reset <pathspec>` to update the index entry, you can
+use linkgit:git-restore[1] to check the contents out of the index to
+the working tree. Alternatively, using linkgit:git-restore[1]
+and specifying a commit with `--source`, you
+can copy the contents of a path out of a commit to the index and to the
+working tree in one go.
+
+`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.
++
+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.
+
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
 
-- 
gitgitgadget

Re: [PATCH 1/4] doc: git-reset: reorder the forms

[Junio C Hamano]

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

> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
> index 3b9ba9aee9..9843682e81 100644
> --- a/Documentation/git-reset.adoc
> +++ b/Documentation/git-reset.adoc
> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
>  SYNOPSIS
>  --------
>  [synopsis]
> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>  git reset [-q] [<tree-ish>] [--] <pathspec>...
>  git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
>  git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>  
>  DESCRIPTION
>  -----------
> -In the first three forms, copy entries from _<tree-ish>_ to the index.
> -In the last form, set the current branch head (`HEAD`) to _<commit>_,
> +In the first form, set the current branch head (`HEAD`) to _<commit>_,
>  optionally modifying index and working tree to match.
>  The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.

In the original, the "defaults to HEAD in all forms" did make sense,
but as the new text does not mention there are three other forms
like the original did, that sentence was made harder to fathom.
I can accept that you do not want to get ahead of yourself to
explain "copy from <treeish>" before you are ready to talk more
about these other forms, but we'd at least need to acknowledge that
what we want to refer to when we say "all forms" here.  Perhaps

    Among the four forms, the first form sets the current branch
    head to ....  In all forms, the tree-ish/commit defaults to
    HEAD.

is easier to read?

> +In the last three forms, copy entries from _<tree-ish>_ to the index.

Or "The other three forms copy entries ..."?

Other than that, looks good to me.

Re: [PATCH 1/4] doc: git-reset: reorder the forms

[Julia Evans]

On Fri, Oct 17, 2025, at 6:20 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
>> index 3b9ba9aee9..9843682e81 100644
>> --- a/Documentation/git-reset.adoc
>> +++ b/Documentation/git-reset.adoc
>> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
>>  SYNOPSIS
>>  --------
>>  [synopsis]
>> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>>  git reset [-q] [<tree-ish>] [--] <pathspec>...
>>  git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
>>  git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
>> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>>  
>>  DESCRIPTION
>>  -----------
>> -In the first three forms, copy entries from _<tree-ish>_ to the index.
>> -In the last form, set the current branch head (`HEAD`) to _<commit>_,
>> +In the first form, set the current branch head (`HEAD`) to _<commit>_,
>>  optionally modifying index and working tree to match.
>>  The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
>
> In the original, the "defaults to HEAD in all forms" did make sense,
> but as the new text does not mention there are three other forms
> like the original did, that sentence was made harder to fathom.

That's true. I didn't pay very careful attention to the text here
because I completely rewrote it in a later patch anyway.
I'll make it say something that makes more sense.

> I can accept that you do not want to get ahead of yourself to
> explain "copy from <treeish>" before you are ready to talk more
> about these other forms, but we'd at least need to acknowledge that
> what we want to refer to when we say "all forms" here.  Perhaps
>
>     Among the four forms, the first form sets the current branch
>     head to ....  In all forms, the tree-ish/commit defaults to
>     HEAD.
>
> is easier to read?
>
>> +In the last three forms, copy entries from _<tree-ish>_ to the index.
>
> Or "The other three forms copy entries ..."?
>
> Other than that, looks good to me.

[PATCH 2/4] doc: git-reset: clarify intro

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action
it does as "Reset ...", commands should not use their name to describe
themselves, and that the word "mode" is used to mean several different
things on this page.

Address these by being more clear about two use cases for `git reset`
("to undo operations" and "to update staged files"), and explaining what
the conditions are for each case instead of forcing the user to figure
out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 9843682e81..876187dc83 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD to point at the specified commit
 
 SYNOPSIS
 --------
@@ -15,10 +15,13 @@ git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
-In the first form, set the current branch head (`HEAD`) to _<commit>_,
-optionally modifying index and working tree to match.
-The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
-In the last three forms, copy entries from _<tree-ish>_ to the index.
+`git reset [<mode>] <commit>` changes which commit HEAD points to.
+This makes it possible to undo various Git operations, for example
+commit, merge, rebase, and pull.
+
+However, when you specify files or directories or pass `--patch`,
+`git reset` will instead update the staged version of the specified
+files without updating HEAD.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and
-- 
gitgitgadget

Re: [PATCH 2/4] doc: git-reset: clarify intro

[Junio C Hamano]

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

> From: Julia Evans <julia@jvns.ca>
>
> From user feedback, there were several points of confusion:
>
> - What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
>   ("I have no clue what the index is", "I've been using git for 20 years
>   and still don't know what a tree-ish is"). Avoid using these terms
>   where it makes sense.
> - What "optionally modifying index and working tree to match" means
>   ("to match what?" "optionally based on what?")
>   Remove this from the intro, we can say it later when giving more
>   details.
> - One user suggested that "The <tree-ish>/<commit> defaults to HEAD
>   in all forms." should be repeated later on, since it's easy to miss.
>   Instead say that HEAD is the default in each case later.
>
> Another issue is that `git reset` consistently describes the action
> it does as "Reset ...", commands should not use their name to describe
> themselves, and that the word "mode" is used to mean several different
> things on this page.
>
> Address these by being more clear about two use cases for `git reset`
> ("to undo operations" and "to update staged files"), and explaining what
> the conditions are for each case instead of forcing the user to figure
> out the pattern is in first form vs the other 3 forms.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-reset.adoc | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
> index 9843682e81..876187dc83 100644
> --- a/Documentation/git-reset.adoc
> +++ b/Documentation/git-reset.adoc
> @@ -3,7 +3,7 @@ git-reset(1)
>  
>  NAME
>  ----
> -git-reset - Reset current HEAD to the specified state
> +git-reset - Set HEAD to point at the specified commit

The command has dual-purpose, and it is a bit disturbing that the
other one is not even mentioned in the original or in the updated
text.  "The other three forms" is about resetting the index without
moving HEAD at all.  Would this work better, I wonder?

    Reset HEAD or index back to a known state

> +`git reset [<mode>] <commit>` changes which commit HEAD points to.
> +This makes it possible to undo various Git operations, for example
> +commit, merge, rebase, and pull.

Good.  These are prime examples of when resetting to a known state
is useful.

> +However, when you specify files or directories or pass `--patch`,
> +`git reset` will instead update the staged version of the specified
> +files without updating HEAD.

I see no however here.

Other forms are not about flipping HEAD to any state we used to have
before.  Instead, they are about populating index entries from the
state taken from an arbitrary tree-ish.

You can view them as enhanced variants of "git reset --mixed HEAD"
(read it as "unstage all changes").  They are enhanced in the sense
that unlike "git reset --mixed HEAD", the treeish the index entries
are taken from does not have to be HEAD, and also in the sense that
unlike "git reset --mixed HEAD", you can limit the index entries to
be affected to a subset of paths.  I am not sure it would make it
easier to understand to explain them in terms of "reset --mixed HEAD"
but I am reasonably sure that it would appear confusing until a
reader realizes that the command has two very disinct mode, one that
is primarily about HEAD, the other that is primarily about index.

>  `git reset [<mode>] [<commit>]`::
>  	This form resets the current branch head to _<commit>_ and

Re: [PATCH 2/4] doc: git-reset: clarify intro

[Julia Evans]

On Fri, Oct 17, 2025, at 6:32 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Julia Evans <julia@jvns.ca>
>>
>> From user feedback, there were several points of confusion:
>>
>> - What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
>>   ("I have no clue what the index is", "I've been using git for 20 years
>>   and still don't know what a tree-ish is"). Avoid using these terms
>>   where it makes sense.
>> - What "optionally modifying index and working tree to match" means
>>   ("to match what?" "optionally based on what?")
>>   Remove this from the intro, we can say it later when giving more
>>   details.
>> - One user suggested that "The <tree-ish>/<commit> defaults to HEAD
>>   in all forms." should be repeated later on, since it's easy to miss.
>>   Instead say that HEAD is the default in each case later.
>>
>> Another issue is that `git reset` consistently describes the action
>> it does as "Reset ...", commands should not use their name to describe
>> themselves, and that the word "mode" is used to mean several different
>> things on this page.
>>
>> Address these by being more clear about two use cases for `git reset`
>> ("to undo operations" and "to update staged files"), and explaining what
>> the conditions are for each case instead of forcing the user to figure
>> out the pattern is in first form vs the other 3 forms.
>>
>> Signed-off-by: Julia Evans <julia@jvns.ca>
>> ---
>>  Documentation/git-reset.adoc | 13 ++++++++-----
>>  1 file changed, 8 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
>> index 9843682e81..876187dc83 100644
>> --- a/Documentation/git-reset.adoc
>> +++ b/Documentation/git-reset.adoc
>> @@ -3,7 +3,7 @@ git-reset(1)
>>  
>>  NAME
>>  ----
>> -git-reset - Reset current HEAD to the specified state
>> +git-reset - Set HEAD to point at the specified commit
>
> The command has dual-purpose, and it is a bit disturbing that the
> other one is not even mentioned in the original or in the updated
> text.  "The other three forms" is about resetting the index without
> moving HEAD at all.  Would this work better, I wonder?
>
>     Reset HEAD or index back to a known state

That's true, though I think we should avoid using "Reset"
to explain what `git reset` does. Perhaps

    Set HEAD or the index to a previous state

>> +`git reset [<mode>] <commit>` changes which commit HEAD points to.
>> +This makes it possible to undo various Git operations, for example
>> +commit, merge, rebase, and pull.
>
> Good.  These are prime examples of when resetting to a known state
> is useful.
>
>> +However, when you specify files or directories or pass `--patch`,
>> +`git reset` will instead update the staged version of the specified
>> +files without updating HEAD.
>
> I see no however here.
>
> Other forms are not about flipping HEAD to any state we used to have
> before.  Instead, they are about populating index entries from the
> state taken from an arbitrary tree-ish.
>
> You can view them as enhanced variants of "git reset --mixed HEAD"
> (read it as "unstage all changes").  They are enhanced in the sense
> that unlike "git reset --mixed HEAD", the treeish the index entries
> are taken from does not have to be HEAD, and also in the sense that
> unlike "git reset --mixed HEAD", you can limit the index entries to
> be affected to a subset of paths.  I am not sure it would make it
> easier to understand to explain them in terms of "reset --mixed HEAD"
> but I am reasonably sure that it would appear confusing until a
> reader realizes that the command has two very disinct mode, one that
> is primarily about HEAD, the other that is primarily about index.
>
>>  `git reset [<mode>] [<commit>]`::
>>  	This form resets the current branch head to _<commit>_ and

I agree that "git reset has two very distinct modes' is important.
Here's an idea for how to communicate that.
It doesn't fully capture all of the nuances of `git reset`'s command
line syntax, but maybe that's not the job of the intro sentence anyway.

I don't love the use of "things" in "two things" but it would be weird to
say "modes" because we already use "mode" to mean something else,
and I haven't thought of something better yet.

`git reset` does two things:

1. `git reset [<mode>] <commit>` changes which commit HEAD points to.
   This makes it possible to undo various Git operations, for example
   commit, merge, rebase, and pull.
2. When you specify files or directories or pass `--patch`, it updates
   the staged version of the specified files.

Re: [PATCH 2/4] doc: git-reset: clarify intro

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

>>     Reset HEAD or index back to a known state
>
> That's true, though I think we should avoid using "Reset"
> to explain what `git reset` does. Perhaps
>
>     Set HEAD or the index to a previous state

OK, though the state is not necessarily "previous".

> I agree that "git reset has two very distinct modes' is important.
> Here's an idea for how to communicate that.
> It doesn't fully capture all of the nuances of `git reset`'s command
> line syntax, but maybe that's not the job of the intro sentence anyway.
>
> I don't love the use of "things" in "two things" but it would be weird to
> say "modes" because we already use "mode" to mean something else,
> and I haven't thought of something better yet.
>
> `git reset` does two things:

I do not mind "things", as long as it is not mislead readers into
thinking that it may do two things at the same time.  "modes" avoids
that problem, as "you use it one way, and it does one thing, and you
use it another way, and it does a very different thing" is the
natural implication of that word.

"The command can be used in two ways"?  "can be used for two
different purposes?"  I dunno.

Re: [PATCH 2/4] doc: git-reset: clarify intro

[D. Ben Knoble]

On Mon, Oct 20, 2025 at 4:02 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Julia Evans" <julia@jvns.ca> writes:
> > I agree that "git reset has two very distinct modes' is important.
> > Here's an idea for how to communicate that.
> > It doesn't fully capture all of the nuances of `git reset`'s command
> > line syntax, but maybe that's not the job of the intro sentence anyway.
> >
> > I don't love the use of "things" in "two things" but it would be weird to
> > say "modes" because we already use "mode" to mean something else,
> > and I haven't thought of something better yet.
> >
> > `git reset` does two things:
>
> I do not mind "things", as long as it is not mislead readers into
> thinking that it may do two things at the same time.  "modes" avoids
> that problem, as "you use it one way, and it does one thing, and you
> use it another way, and it does a very different thing" is the
> natural implication of that word.
>
> "The command can be used in two ways"?  "can be used for two
> different purposes?"  I dunno.

Some options:

    `git reset` does one of two different things

    `git reset` can be used to accomplish either of the following:

-- 
D. Ben Knoble

Re: [PATCH 2/4] doc: git-reset: clarify intro

[Julia Evans]

I was hoping to be able to finish this, but I don't have funding to
work on the Git docs (I imagine like everyone else who works on them! :) )
and the time I budgeted to do this work has run out for now.

It's been really interesting to get to dig into the Git documentation
and I really appreciate all of the reviews & encouragement along the way.

all the best,
Julia

On Mon, Oct 20, 2025, at 3:29 PM, Julia Evans wrote:
> On Fri, Oct 17, 2025, at 6:32 PM, Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>>> From: Julia Evans <julia@jvns.ca>
>>>
>>> From user feedback, there were several points of confusion:
>>>
>>> - What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
>>>   ("I have no clue what the index is", "I've been using git for 20 years
>>>   and still don't know what a tree-ish is"). Avoid using these terms
>>>   where it makes sense.
>>> - What "optionally modifying index and working tree to match" means
>>>   ("to match what?" "optionally based on what?")
>>>   Remove this from the intro, we can say it later when giving more
>>>   details.
>>> - One user suggested that "The <tree-ish>/<commit> defaults to HEAD
>>>   in all forms." should be repeated later on, since it's easy to miss.
>>>   Instead say that HEAD is the default in each case later.
>>>
>>> Another issue is that `git reset` consistently describes the action
>>> it does as "Reset ...", commands should not use their name to describe
>>> themselves, and that the word "mode" is used to mean several different
>>> things on this page.
>>>
>>> Address these by being more clear about two use cases for `git reset`
>>> ("to undo operations" and "to update staged files"), and explaining what
>>> the conditions are for each case instead of forcing the user to figure
>>> out the pattern is in first form vs the other 3 forms.
>>>
>>> Signed-off-by: Julia Evans <julia@jvns.ca>
>>> ---
>>>  Documentation/git-reset.adoc | 13 ++++++++-----
>>>  1 file changed, 8 insertions(+), 5 deletions(-)
>>>
>>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
>>> index 9843682e81..876187dc83 100644
>>> --- a/Documentation/git-reset.adoc
>>> +++ b/Documentation/git-reset.adoc
>>> @@ -3,7 +3,7 @@ git-reset(1)
>>>  
>>>  NAME
>>>  ----
>>> -git-reset - Reset current HEAD to the specified state
>>> +git-reset - Set HEAD to point at the specified commit
>>
>> The command has dual-purpose, and it is a bit disturbing that the
>> other one is not even mentioned in the original or in the updated
>> text.  "The other three forms" is about resetting the index without
>> moving HEAD at all.  Would this work better, I wonder?
>>
>>     Reset HEAD or index back to a known state
>
> That's true, though I think we should avoid using "Reset"
> to explain what `git reset` does. Perhaps
>
>     Set HEAD or the index to a previous state
>
>>> +`git reset [<mode>] <commit>` changes which commit HEAD points to.
>>> +This makes it possible to undo various Git operations, for example
>>> +commit, merge, rebase, and pull.
>>
>> Good.  These are prime examples of when resetting to a known state
>> is useful.
>>
>>> +However, when you specify files or directories or pass `--patch`,
>>> +`git reset` will instead update the staged version of the specified
>>> +files without updating HEAD.
>>
>> I see no however here.
>>
>> Other forms are not about flipping HEAD to any state we used to have
>> before.  Instead, they are about populating index entries from the
>> state taken from an arbitrary tree-ish.
>>
>> You can view them as enhanced variants of "git reset --mixed HEAD"
>> (read it as "unstage all changes").  They are enhanced in the sense
>> that unlike "git reset --mixed HEAD", the treeish the index entries
>> are taken from does not have to be HEAD, and also in the sense that
>> unlike "git reset --mixed HEAD", you can limit the index entries to
>> be affected to a subset of paths.  I am not sure it would make it
>> easier to understand to explain them in terms of "reset --mixed HEAD"
>> but I am reasonably sure that it would appear confusing until a
>> reader realizes that the command has two very disinct mode, one that
>> is primarily about HEAD, the other that is primarily about index.
>>
>>>  `git reset [<mode>] [<commit>]`::
>>>  	This form resets the current branch head to _<commit>_ and
>
> I agree that "git reset has two very distinct modes' is important.
> Here's an idea for how to communicate that.
> It doesn't fully capture all of the nuances of `git reset`'s command
> line syntax, but maybe that's not the job of the intro sentence anyway.
>
> I don't love the use of "things" in "two things" but it would be weird to
> say "modes" because we already use "mode" to mean something else,
> and I haven't thought of something better yet.
>
> `git reset` does two things:
>
> 1. `git reset [<mode>] <commit>` changes which commit HEAD points to.
>    This makes it possible to undo various Git operations, for example
>    commit, merge, rebase, and pull.
> 2. When you specify files or directories or pass `--patch`, it updates
>    the staged version of the specified files.

[PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences
between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning `git merge --abort` since my best guess is that
   most folks want to use that instead of `git reset --merge`.
3. Issues telling the difference between --soft and --mixed, as well as
   --keep. Leave --keep alone because I couldn't understand its use case,
   but change `--soft` / `--mixed` / `--hard` as follows:

--mixed is the default, so put it first.

Describe --soft/--mixed/--hard with the following structure:

* Start by saying what happens to the files in the working directory,
  because the thing users want to avoid most is irretrievably losing
  changes to their working directory files.
* Then describe what happens to the staging area. Right now it seems to
  frame leaving the index alone as being a sort of neutral action.
  I think this is part of what's confusing users, because in Git when
  you update HEAD, Git almost always updates the index to match HEAD.
  So leaving the index unchanged while updating HEAD is actually quite
  unusual, and it deserves to be flagged.
* Finally, give an example for --soft to explain a common use case.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 42 +++++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 876187dc83..fa4bb2b551 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -24,42 +24,44 @@ However, when you specify files or directories or pass `--patch`,
 files without updating HEAD.
 
 `git reset [<mode>] [<commit>]`::
-	This form resets the current branch head to _<commit>_ and
-	possibly updates the index (resetting it to the tree of _<commit>_) and
-	the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
-	is set to the tip of the current branch. If _<mode>_ is omitted,
-	defaults to `--mixed`. The _<mode>_ must be one of the following:
+	Set the current branch head (`HEAD`) to point at _<commit>_.
+	Depending on _<mode>_, also update the working directory and/or index
+	to match the contents of _<commit>_.
+	_<commit>_ defaults to `HEAD`.
+	Before the operation, `ORIG_HEAD` is set to the tip of the current branch.
++
+The _<mode>_ must be one of the following (default `--mixed`):
 +
---
-`--soft`::
-	Does not touch the index file or the working tree at all (but
-	resets the head to _<commit>_, just like all modes do). This leaves
-	all your changed files "Changes to be committed", as `git status`
-	would put it.
 
+--
 `--mixed`::
-	Resets the index but not the working tree (i.e., the changed files
-	are preserved but not marked for commit) and reports what has not
-	been updated. This is the default action.
+	Leaves your working directory unchanged.
+	Updates the index to match the new HEAD, so nothing will be staged.
 +
 If `-N` is specified, removed paths are marked as intent-to-add (see
 linkgit:git-add[1]).
 
+`--soft`::
+	Leaves your working directory unchanged. The index is left unchanged,
+	so everything in your current commit will be staged.
+	For example, if you have no staged changes, you can use
+	`git reset --soft HEAD~5; git commit`
+	to combine the last 5 commits into 1 commit.
+
 `--hard`::
-	Resets the index and working tree. Any changes to tracked files in the
-	working tree since _<commit>_ are discarded.  Any untracked files or
-	directories in the way of writing any tracked files are simply deleted.
+	Overwrites all files and directories with the version from _<commit>_,
+	and may overwrite untracked files.
+	Updates the index to match the new HEAD, so nothing will be staged.
 
 `--merge`::
+	Mainly exists for backwards compatibility: `git merge --abort` is the
+	usual way to abort a merge. See linkgit:git-merge[1] for the differences.
 	Resets the index and 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 (i.e. which have changes
 	which have not been added).
 	If a file that is different between _<commit>_ and the index has
 	unstaged changes, reset is aborted.
-+
-In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
-but carries forward unmerged index entries.
 
 `--keep`::
 	Resets index entries and updates files in the working tree that are
-- 
gitgitgadget

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

[Junio C Hamano]

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

> +`--soft`::
> +	Leaves your working directory unchanged. The index is left unchanged,

Why not "leave your working tree files and the index unchanged"?

> +	so everything in your current commit will be staged.

Hmph, if a reader still has the "stage the changes" mental model,
then this would be true only when you are resetting to HEAD~1 (this
is one of the reasons why I am hesitant to overuse the verb
"stage").  If you are going to HEAD~5, such a reader would say that
the changes made by the past 5 commits are staged, not just the
commit you are on before resetting.

> +	For example, if you have no staged changes, you can use
> +	`git reset --soft HEAD~5; git commit`
> +	to combine the last 5 commits into 1 commit.

Another thing that may be worth mentioning is that you can do this
even with local changes in the working tree, because you do not give
"-a" to the final "git commit".

>  `--hard`::
> -	Resets the index and working tree. Any changes to tracked files in the
> -	working tree since _<commit>_ are discarded.  Any untracked files or
> -	directories in the way of writing any tracked files are simply deleted.
> +	Overwrites all files and directories with the version from _<commit>_,
> +	and may overwrite untracked files.
> +	Updates the index to match the new HEAD, so nothing will be staged.

One thing that may be worth saying is that the paths in the working
tree that are tracked in the index that are not in <commit> will
disappear.

>  `--merge`::
> +	Mainly exists for backwards compatibility: `git merge --abort` is the
> +	usual way to abort a merge. See linkgit:git-merge[1] for the differences.

There are operations that are not "git merge" that can leave the
index in an unmerged state, and you do not want to use "git merge
--abort" to get out of such a state, I would imagine.  So I have a
feeling that we are better off without these two lines.

>  	Resets the index and 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 (i.e. which have changes
>  	which have not been added).
>  	If a file that is different between _<commit>_ and the index has
>  	unstaged changes, reset is aborted.
> -+
> -In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
> -but carries forward unmerged index entries.

I do not mind losing this.  Unlike the time back when these two
lines were written, nobody knows (and more importantly, nobody has
to know) what "read-tree -u -m" does, these days.

>  `--keep`::
>  	Resets index entries and updates files in the working tree that are

Thanks.

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

[Julia Evans]

On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> +`--soft`::
>> +	Leaves your working directory unchanged. The index is left unchanged,
>
> Why not "leave your working tree files and the index unchanged"?

The reason I say "working directory" instead of "working tree" is that
I've seen a few comments from users saying that they don't know
what "working tree" means. I'm still not sure what the reason for
calling it a "working tree" is.

The reason for keeping them separate sentences is just for symmetry with
the other commands, and also because (like I mentioned in the commit
message) "leaving X and Y unchanged" makes it sound like leaving X and
Y unchanged is a "neutral operation", while actually leaving the index
unchanged while updating HEAD is actually a fairly weird thing to do.

>> +	so everything in your current commit will be staged.
>
> Hmph, if a reader still has the "stage the changes" mental model,
> then this would be true only when you are resetting to HEAD~1 (this
> is one of the reasons why I am hesitant to overuse the verb
> "stage").  If you are going to HEAD~5, such a reader would say that
> the changes made by the past 5 commits are staged, not just the
> commit you are on before resetting.

That's fair. I'll try to think about whether there's a better way to say
this.

Previously it said "This leaves all your changed files
"Changes to be committed", as git status would put it.", which has the
same issue ("changed files" since when exactly?).
Maybe I can fix this by being more explicit about which changes
exactly will show up as "staged" in `git status`.

>> +	For example, if you have no staged changes, you can use
>> +	`git reset --soft HEAD~5; git commit`
>> +	to combine the last 5 commits into 1 commit.
>
> Another thing that may be worth mentioning is that you can do this
> even with local changes in the working tree, because you do not give
> "-a" to the final "git commit".

Maybe! I'm not sure if we want to encourage doing complex Git operations
with unstaged changes though. I feel like it often leads to suffering
and I think people who want to do that can already infer that it's
possible.

>>  `--hard`::
>> -	Resets the index and working tree. Any changes to tracked files in the
>> -	working tree since _<commit>_ are discarded.  Any untracked files or
>> -	directories in the way of writing any tracked files are simply deleted.
>> +	Overwrites all files and directories with the version from _<commit>_,
>> +	and may overwrite untracked files.
>> +	Updates the index to match the new HEAD, so nothing will be staged.
>
> One thing that may be worth saying is that the paths in the working
> tree that are tracked in the index that are not in <commit> will
> disappear.

Interesting, I don't think I knew that. Would this be a more accurate
description of what `git reset --hard` does, conceptually?
I want to make sure I understand how it works.

1. List every file that's either in the target commit or in the index
2. For each file, make it match the target commit
    (overwriting untracked files if necessary)

>>  `--merge`::
>> +	Mainly exists for backwards compatibility: `git merge --abort` is the
>> +	usual way to abort a merge. See linkgit:git-merge[1] for the differences.
>
> There are operations that are not "git merge" that can leave the
> index in an unmerged state, and you do not want to use "git merge
> --abort" to get out of such a state, I would imagine.  So I have a
> feeling that we are better off without these two lines.

Do you mean `git reset` and `git cherry-pick`, or are there other operations
that can leave the operation in an unmerged state?
My mental model is that if there's a merge conflict, the best way to deal with it
is to use the appropriate `--abort` command (depending on how you got there),
because the command-specific `--abort` will know how to do things like
restore autostashed changes. But I agree that just saying "use `git merge --abort`
is not a complete description.

>>  	Resets the index and 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 (i.e. which have changes
>>  	which have not been added).
>>  	If a file that is different between _<commit>_ and the index has
>>  	unstaged changes, reset is aborted.
>> -+
>> -In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
>> -but carries forward unmerged index entries.
>
> I do not mind losing this.  Unlike the time back when these two
> lines were written, nobody knows (and more importantly, nobody has
> to know) what "read-tree -u -m" does, these days.

Thanks, it's useful for me to know more about the context at the time
this was written.

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

[D. Ben Knoble]

On Mon, Oct 20, 2025 at 4:28 PM Julia Evans <julia@jvns.ca> wrote:
>
> On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:
> > "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >
> >> +`--soft`::
> >> +    Leaves your working directory unchanged. The index is left unchanged,
> >
> > Why not "leave your working tree files and the index unchanged"?
>
> The reason I say "working directory" instead of "working tree" is that
> I've seen a few comments from users saying that they don't know
> what "working tree" means. I'm still not sure what the reason for
> calling it a "working tree" is.

At a guess: suppose I have a non-bare repository ~/code/git with
corresponding ~/code/git/.git directory, but PWD=~/code/git/t. Then my
working directory is "…/t" but my working tree includes all the stuff
Git is tracking above me, too! (It also helps draw parallelism with
git-worktree, but that's a bit circular.)

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

> On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>>> +`--soft`::
>>> +	Leaves your working directory unchanged. The index is left unchanged,
>>
>> Why not "leave your working tree files and the index unchanged"?
>
> The reason I say "working directory" instead of "working tree" is that
> I've seen a few comments from users saying that they don't know
> what "working tree" means. I'm still not sure what the reason for
> calling it a "working tree" is.

"working tree" refers to the directory that is the top level of a
checkout; I'd view (current) "working directory" can be anything
$(pwd), that may be outside control of any git repository, and that
is why I tend to avoid the latter when I want to be more precise
(and "worktree" is another thing---used to refer to one particular
"working tree" among other working trees attached to the same
repository).

But that distinction was not the part I wanted to comment on.  The
question was about two sentences talking about two things
separately.  IOW

	Leave your working directory and the index unchanged.

is what I would have expected, and I was wondering why they are
treated separately.  After all, the index is part of your working
tree state.

> The reason for keeping them separate sentences is just for symmetry with
> the other commands, and also because (like I mentioned in the commit
> message) "leaving X and Y unchanged" makes it sound like leaving X and
> Y unchanged is a "neutral operation", while actually leaving the index
> unchanged while updating HEAD is actually a fairly weird thing to do.

Sorry, but I do not understand this comment.

The index and the HEAD are two different things, and it is natural
that they can move independently.  After all we update the former
without updating the latter all the time (it is called "git add").

Besides, the two things the --soft does not touch are the files in
the working tree and the index.  The index has what you want to make
the next commit out of, and the working tree has the state that may
come after that state in the index.  Keeping both of them intact
when moving HEAD around is one natural thing to do when you want to
squash the previous N commits after "git add <paths>" by doing "git
reset --soft HEAD~N && git commit".  Contrasting to that, "--mixed"
would leave the files in the working tree intact, while matching the
index to the HEAD you are moving to, essentially undoing your "git
add"s before you decided to reset.  That's another natural thing to
do when you decide to keep the clean slate and rebuild your index from
scratch to prepare for a commit that comes on top of the commit you
are moving to.

So, no, I do not understand the above comment.

> Do you mean `git reset` and `git cherry-pick`, or are there other operations
> that can leave the operation in an unmerged state?

There are many commands that leaves the index unmerged, like "am
-3", "rebase", "switch -m", "stash pop", etc.

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

[Julia Evans via GitGitGadget]

From: Julia Evans <julia@jvns.ca>

From user feedback:

- Continued confusion about the terms "tree-ish" and "pathspec"
- The word "hunks" is confusing folks, use "changes" instead.
- On the part about `git restore`, there were a few comments to the
  effect of "wait, this doesn't actually update any files? What? Why?"
  Be more direct that `git reset` does not update files: there's no
  obvious reason to suggest that folks use `git reset` followed by `git
  restore`, instead suggest just using `git restore`.

Continue avoiding the use of the word "reset" to
describe what "git reset" does.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 27 +++++++++++----------------
 1 file changed, 11 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index fa4bb2b551..52d380a756 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -79,29 +79,24 @@ linkgit:git-add[1]).
 
 `git reset [-q] [<tree-ish>] [--] <pathspec>...`::
 `git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
-	These forms reset the index entries for all paths that match the
-	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
-	the working tree or the current branch.)
+	For all specified files or directories, set the staged version to
+	the version from the given commit or tree (which defaults to `HEAD`).
 +
 This means that `git reset <pathspec>` is the opposite of `git add
-<pathspec>`. This command is equivalent to
-`git restore [--source=<tree-ish>] --staged <pathspec>...`.
+<pathspec>`: it unstages all changes to the specified file(s) or
+directories. This is equivalent to `git restore --staged <pathspec>...`.
 +
-After running `git reset <pathspec>` to update the index entry, you can
-use linkgit:git-restore[1] to check the contents out of the index to
-the working tree. Alternatively, using linkgit:git-restore[1]
-and specifying a commit with `--source`, you
-can copy the contents of a path out of a commit to the index and to the
-working tree in one go.
+`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.
 
 `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.
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
-- 
gitgitgadget

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

[Junio C Hamano]

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

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

[Ben Knoble]

> Le 17 oct. 2025 à 19:25, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Julia Evans via GitGitGadget" <gitgitgadget@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 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.

I think the issue was the word « hunk », not « patch ».

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

[Junio C Hamano]

Ben Knoble <ben.knoble@gmail.com> writes:

>> Le 17 oct. 2025 à 19:25, Junio C Hamano <gitster@pobox.com> a écrit :
>> 
>> "Julia Evans via GitGitGadget" <gitgitgadget@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 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.
>
> I think the issue was the word « hunk », not « patch ».

I know.  That is exactly where my question comes from.

[PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section

[D. Ben Knoble]

This continues Julia Evans's excellent work updating the git-reset docs.

Changes in v2:
- Mostly address Junio's review while keeping to Julia's style (?),
  taking at a stab at a few gray areas.
- I left alone the first patch, the commented-upon part of which is
  later rewritten anyway.

v1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset

Julia Evans (4):
  doc: git-reset: reorder the forms
  doc: git-reset: clarify intro
  doc: git-reset: clarify `git reset [mode]`
  doc: git-reset: clarify `git reset <pathspec>`

 Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 51 deletions(-)

Diff-intervalle contre v1 :
1:  5074fbf4ea ! 1:  a558c5a868 doc: git-reset: reorder the forms
    @@ Metadata
      ## Commit message ##
         doc: git-reset: reorder the forms
     
    -    >From user feedback: three users commented that the `git reset [mode]`
    +    From user feedback: three users commented that the `git reset [mode]`
         form is the one that they primarily use, and that they were suprised to
         see it listed last.
         ("I've never used git reset in any mode other than --hard").
2:  c7049edf39 ! 2:  f90be8559f doc: git-reset: clarify intro
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify intro
     
    -    >From user feedback, there were several points of confusion:
    +    From user feedback, there were several points of confusion:
     
         - What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
           ("I have no clue what the index is", "I've been using git for 20 years
    @@ Documentation/git-reset.adoc: git-reset(1)
      NAME
      ----
     -git-reset - Reset current HEAD to the specified state
    -+git-reset - Set HEAD to point at the specified commit
    ++git-reset - Set HEAD or the index to a known state
      
      SYNOPSIS
      --------
    @@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
     -optionally modifying index and working tree to match.
     -The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
     -In the last three forms, copy entries from _<tree-ish>_ to the index.
    -+`git reset [<mode>] <commit>` changes which commit HEAD points to.
    -+This makes it possible to undo various Git operations, for example
    -+commit, merge, rebase, and pull.
    ++`git reset` does either of the following:
     +
    -+However, when you specify files or directories or pass `--patch`,
    -+`git reset` will instead update the staged version of the specified
    -+files without updating HEAD.
    ++1. `git reset [<mode>] <commit>` changes which commit HEAD points to. This makes
    ++   it possible to undo various Git operations, for example commit, merge,
    ++   rebase, and pull.
    ++2. When you specify files or directories or pass `--patch`, `git reset` updates
    ++   the staged version of the specified files.
      
      `git reset [<mode>] [<commit>]`::
      	This form resets the current branch head to _<commit>_ and
3:  84aed17da6 ! 3:  89c87c14aa doc: git-reset: clarify `git reset [mode]`
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify `git reset [mode]`
     
    -    >From user feedback, there was some confusion about the differences
    +    From user feedback, there was some confusion about the differences
         between the modes, including:
     
         1. Sometimes it says "index" and sometimes "index file".
            Fix by replacing "index file" with "index".
         2. Many comments about not being able to understand what `--merge` does.
    -       Fix by mentioning `git merge --abort` since my best guess is that
    -       most folks want to use that instead of `git reset --merge`.
    +       Fix by mentioning obscure situations, since that seems to be what
    +       it's for. Most folks will use `git <cmd> --abort`.
         3. Issues telling the difference between --soft and --mixed, as well as
            --keep. Leave --keep alone because I couldn't understand its use case,
            but change `--soft` / `--mixed` / `--hard` as follows:
    @@ Commit message
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## Documentation/git-reset.adoc ##
    -@@ Documentation/git-reset.adoc: However, when you specify files or directories or pass `--patch`,
    - files without updating HEAD.
    +@@ Documentation/git-reset.adoc: DESCRIPTION
    +    the staged version of the specified files.
      
      `git reset [<mode>] [<commit>]`::
     -	This form resets the current branch head to _<commit>_ and
    @@ Documentation/git-reset.adoc: However, when you specify files or directories or
      linkgit:git-add[1]).
      
     +`--soft`::
    -+	Leaves your working directory unchanged. The index is left unchanged,
    -+	so everything in your current commit will be staged.
    ++	Leave your working tree files and the index unchanged.
     +	For example, if you have no staged changes, you can use
     +	`git reset --soft HEAD~5; git commit`
    -+	to combine the last 5 commits into 1 commit.
    ++	to combine the last 5 commits into 1 commit. This works even with
    ++	changes in the working tree, which are left untouched, but such usage
    ++	can lead to confusion.
     +
      `--hard`::
     -	Resets the index and working tree. Any changes to tracked files in the
     -	working tree since _<commit>_ are discarded.  Any untracked files or
     -	directories in the way of writing any tracked files are simply deleted.
     +	Overwrites all files and directories with the version from _<commit>_,
    -+	and may overwrite untracked files.
    ++	and may overwrite untracked files. Tracked files not in _<commit>_ are
    ++	removed so that the working tree matches _<commit>_.
     +	Updates the index to match the new HEAD, so nothing will be staged.
      
      `--merge`::
    -+	Mainly exists for backwards compatibility: `git merge --abort` is the
    -+	usual way to abort a merge. See linkgit:git-merge[1] for the differences.
    ++	Mainly exists to reset unmerged index entries, like those left behind by
    ++	`git am -3` or `git switch -m` in certain situations.
      	Resets the index and 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 (i.e. which have changes
4:  0b9583f872 ! 4:  d6582dc53c doc: git-reset: clarify `git reset <pathspec>`
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify `git reset <pathspec>`
     
    -    >From user feedback:
    +    From user feedback:
     
         - Continued confusion about the terms "tree-ish" and "pathspec"
         - The word "hunks" is confusing folks, use "changes" instead.
    @@ Documentation/git-reset.adoc: linkgit:git-add[1]).
     -and specifying a commit with `--source`, you
     -can copy the contents of a path out of a commit to the index and to the
     -working tree in one go.
    -+`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.
    ++In this mode, `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 linkgit:git-restore[1].
      
      `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
     -	Interactively select hunks in the difference between the index
    @@ Documentation/git-reset.adoc: linkgit:git-add[1]).
     -	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.
    ++	The chosen changes are added to the index.
      +
      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"
-- 
2.52.0.rc0.365.g9bf09b728d.dirty

[PATCH v2 1/4] doc: git-reset: reorder the forms

[D. Ben Knoble]

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]`
form is the one that they primarily use, and that they were suprised to
see it listed last.
("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what
"Reset current HEAD to the specified state" at the beginning refers
to, and because the `git reset [mode]` form is the only thing that
`git reset` uniquely does, the others could also be done with
`git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 3b9ba9aee9..9843682e81 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
 SYNOPSIS
 --------
 [synopsis]
+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
 git reset [-q] [<tree-ish>] [--] <pathspec>...
 git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
 git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
 
 DESCRIPTION
 -----------
-In the first three forms, copy entries from _<tree-ish>_ to the index.
-In the last form, set the current branch head (`HEAD`) to _<commit>_,
+In the first form, set the current branch head (`HEAD`) to _<commit>_,
 optionally modifying index and working tree to match.
 The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
-
-`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
-`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
-	These forms reset the index entries for all paths that match the
-	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
-	the working tree or the current branch.)
-+
-This means that `git reset <pathspec>` is the opposite of `git add
-<pathspec>`. This command is equivalent to
-`git restore [--source=<tree-ish>] --staged <pathspec>...`.
-+
-After running `git reset <pathspec>` to update the index entry, you can
-use linkgit:git-restore[1] to check the contents out of the index to
-the working tree. Alternatively, using linkgit:git-restore[1]
-and specifying a commit with `--source`, you
-can copy the contents of a path out of a commit to the index and to the
-working tree in one go.
-
-`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.
-+
-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.
+In the last three forms, copy entries from _<tree-ish>_ to the index.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and
@@ -98,6 +72,32 @@ but carries forward unmerged index entries.
 	the submodules' `HEAD` to be detached at that commit.
 --
 
+`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
+`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
+	These forms reset the index entries for all paths that match the
+	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
+	the working tree or the current branch.)
++
+This means that `git reset <pathspec>` is the opposite of `git add
+<pathspec>`. This command is equivalent to
+`git restore [--source=<tree-ish>] --staged <pathspec>...`.
++
+After running `git reset <pathspec>` to update the index entry, you can
+use linkgit:git-restore[1] to check the contents out of the index to
+the working tree. Alternatively, using linkgit:git-restore[1]
+and specifying a commit with `--source`, you
+can copy the contents of a path out of a commit to the index and to the
+working tree in one go.
+
+`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.
++
+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.
+
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
 
-- 
2.52.0.rc0.365.g9bf09b728d.dirty

[PATCH v2 2/4] doc: git-reset: clarify intro

[D. Ben Knoble]

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action
it does as "Reset ...", commands should not use their name to describe
themselves, and that the word "mode" is used to mean several different
things on this page.

Address these by being more clear about two use cases for `git reset`
("to undo operations" and "to update staged files"), and explaining what
the conditions are for each case instead of forcing the user to figure
out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 9843682e81..71e8f52430 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD or the index to a known state
 
 SYNOPSIS
 --------
@@ -15,10 +15,13 @@ git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
-In the first form, set the current branch head (`HEAD`) to _<commit>_,
-optionally modifying index and working tree to match.
-The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
-In the last three forms, copy entries from _<tree-ish>_ to the index.
+`git reset` does either of the following:
+
+1. `git reset [<mode>] <commit>` changes which commit HEAD points to. This makes
+   it possible to undo various Git operations, for example commit, merge,
+   rebase, and pull.
+2. When you specify files or directories or pass `--patch`, `git reset` updates
+   the staged version of the specified files.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and
-- 
2.52.0.rc0.365.g9bf09b728d.dirty

[PATCH v2 3/4] doc: git-reset: clarify `git reset [mode]`

[D. Ben Knoble]

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences
between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning obscure situations, since that seems to be what
   it's for. Most folks will use `git <cmd> --abort`.
3. Issues telling the difference between --soft and --mixed, as well as
   --keep. Leave --keep alone because I couldn't understand its use case,
   but change `--soft` / `--mixed` / `--hard` as follows:

--mixed is the default, so put it first.

Describe --soft/--mixed/--hard with the following structure:

* Start by saying what happens to the files in the working directory,
  because the thing users want to avoid most is irretrievably losing
  changes to their working directory files.
* Then describe what happens to the staging area. Right now it seems to
  frame leaving the index alone as being a sort of neutral action.
  I think this is part of what's confusing users, because in Git when
  you update HEAD, Git almost always updates the index to match HEAD.
  So leaving the index unchanged while updating HEAD is actually quite
  unusual, and it deserves to be flagged.
* Finally, give an example for --soft to explain a common use case.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 71e8f52430..6de0d524c3 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -24,42 +24,46 @@ DESCRIPTION
    the staged version of the specified files.
 
 `git reset [<mode>] [<commit>]`::
-	This form resets the current branch head to _<commit>_ and
-	possibly updates the index (resetting it to the tree of _<commit>_) and
-	the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
-	is set to the tip of the current branch. If _<mode>_ is omitted,
-	defaults to `--mixed`. The _<mode>_ must be one of the following:
+	Set the current branch head (`HEAD`) to point at _<commit>_.
+	Depending on _<mode>_, also update the working directory and/or index
+	to match the contents of _<commit>_.
+	_<commit>_ defaults to `HEAD`.
+	Before the operation, `ORIG_HEAD` is set to the tip of the current branch.
++
+The _<mode>_ must be one of the following (default `--mixed`):
 +
---
-`--soft`::
-	Does not touch the index file or the working tree at all (but
-	resets the head to _<commit>_, just like all modes do). This leaves
-	all your changed files "Changes to be committed", as `git status`
-	would put it.
 
+--
 `--mixed`::
-	Resets the index but not the working tree (i.e., the changed files
-	are preserved but not marked for commit) and reports what has not
-	been updated. This is the default action.
+	Leaves your working directory unchanged.
+	Updates the index to match the new HEAD, so nothing will be staged.
 +
 If `-N` is specified, removed paths are marked as intent-to-add (see
 linkgit:git-add[1]).
 
+`--soft`::
+	Leave your working tree files and the index unchanged.
+	For example, if you have no staged changes, you can use
+	`git reset --soft HEAD~5; git commit`
+	to combine the last 5 commits into 1 commit. This works even with
+	changes in the working tree, which are left untouched, but such usage
+	can lead to confusion.
+
 `--hard`::
-	Resets the index and working tree. Any changes to tracked files in the
-	working tree since _<commit>_ are discarded.  Any untracked files or
-	directories in the way of writing any tracked files are simply deleted.
+	Overwrites all files and directories with the version from _<commit>_,
+	and may overwrite untracked files. Tracked files not in _<commit>_ are
+	removed so that the working tree matches _<commit>_.
+	Updates the index to match the new HEAD, so nothing will be staged.
 
 `--merge`::
+	Mainly exists to reset unmerged index entries, like those left behind by
+	`git am -3` or `git switch -m` in certain situations.
 	Resets the index and 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 (i.e. which have changes
 	which have not been added).
 	If a file that is different between _<commit>_ and the index has
 	unstaged changes, reset is aborted.
-+
-In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
-but carries forward unmerged index entries.
 
 `--keep`::
 	Resets index entries and updates files in the working tree that are
-- 
2.52.0.rc0.365.g9bf09b728d.dirty

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

[D. Ben Knoble]

From: Julia Evans <julia@jvns.ca>

From user feedback:

- Continued confusion about the terms "tree-ish" and "pathspec"
- The word "hunks" is confusing folks, use "changes" instead.
- On the part about `git restore`, there were a few comments to the
  effect of "wait, this doesn't actually update any files? What? Why?"
  Be more direct that `git reset` does not update files: there's no
  obvious reason to suggest that folks use `git reset` followed by `git
  restore`, instead suggest just using `git restore`.

Continue avoiding the use of the word "reset" to
describe what "git reset" does.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 6de0d524c3..ab7f565286 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -81,29 +81,25 @@ linkgit:git-add[1]).
 
 `git reset [-q] [<tree-ish>] [--] <pathspec>...`::
 `git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
-	These forms reset the index entries for all paths that match the
-	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
-	the working tree or the current branch.)
+	For all specified files or directories, set the staged version to
+	the version from the given commit or tree (which defaults to `HEAD`).
 +
 This means that `git reset <pathspec>` is the opposite of `git add
-<pathspec>`. This command is equivalent to
-`git restore [--source=<tree-ish>] --staged <pathspec>...`.
+<pathspec>`: it unstages all changes to the specified file(s) or
+directories. This is equivalent to `git restore --staged <pathspec>...`.
 +
-After running `git reset <pathspec>` to update the index entry, you can
-use linkgit:git-restore[1] to check the contents out of the index to
-the working tree. Alternatively, using linkgit:git-restore[1]
-and specifying a commit with `--source`, you
-can copy the contents of a path out of a commit to the index and to the
-working tree in one go.
+In this mode, `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 linkgit:git-restore[1].
 
 `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.
 +
 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.
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
-- 
2.52.0.rc0.365.g9bf09b728d.dirty

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

[Junio C Hamano]

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