From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>,
"D. Ben Knoble" <ben.knoble@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 2/4] doc: git-reset: clarify intro
Date: Wed, 03 Dec 2025 13:15:01 -0500 [thread overview]
Message-ID: <b09c955f-06d1-4dcd-949d-cc723a9604ac@app.fastmail.com> (raw)
In-Reply-To: <4871df7e-4ab4-45ea-83bd-9a49e4d60561@app.fastmail.com>
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.
next prev parent reply other threads:[~2025-12-03 18:15 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-17 20:05 [PATCH 0/4] doc: git-reset: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-17 20:05 ` [PATCH 1/4] doc: git-reset: reorder the forms Julia Evans via GitGitGadget
2025-10-17 22:20 ` Junio C Hamano
2025-10-20 19:03 ` Julia Evans
2025-10-17 20:05 ` [PATCH 2/4] doc: git-reset: clarify intro Julia Evans via GitGitGadget
2025-10-17 22:32 ` Junio C Hamano
2025-10-20 19:29 ` Julia Evans
2025-10-20 20:00 ` Junio C Hamano
2025-10-20 20:30 ` D. Ben Knoble
2025-12-03 18:15 ` Julia Evans [this message]
2025-10-17 20:05 ` [PATCH 3/4] doc: git-reset: clarify `git reset [mode]` Julia Evans via GitGitGadget
2025-10-18 4:53 ` Junio C Hamano
2025-10-20 20:23 ` Julia Evans
2025-10-20 20:33 ` D. Ben Knoble
2025-10-20 20:44 ` Junio C Hamano
2025-10-17 20:05 ` [PATCH 4/4] doc: git-reset: clarify `git reset <pathspec>` Julia Evans via GitGitGadget
2025-10-17 23:25 ` Junio C Hamano
2025-10-18 14:06 ` Ben Knoble
2025-10-18 16:17 ` Junio C Hamano
2025-12-19 0:23 ` [PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 2/4] doc: git-reset: clarify intro D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2025-12-30 5:23 ` Junio C Hamano
2026-01-01 22:32 ` D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-02 13:49 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-02 14:28 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-07 3:55 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b09c955f-06d1-4dcd-949d-cc723a9604ac@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox