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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 20, 2025, 20:00 UTC
Message-ID: <xmqqjz0pz6l4.fsf@gitster.g>
In-Reply-To: <4871df7e-4ab4-45ea-83bd-9a49e4d60561@app.fastmail.com>

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

Show 6 quoted lines

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

Show 10 quoted lines

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