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

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