From: Julia Evans Date: Wed, 03 Dec 2025 18:15:01 GMT Subject: Re: [PATCH 2/4] doc: git-reset: clarify intro Message-ID: 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" writes: >> >>> From: Julia Evans >>> >>> 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 / 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 >>> --- >>> 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 [] ` 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 [] []`:: >>> This form resets the current branch head to __ 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 [] ` 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.