Re: [PATCH 1/4] doc: git-reset: reorder the forms
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 20, 2025, 19:03 UTC
- Message-ID
- <8099e7ef-2673-407e-8cca-e6b566b99549@app.fastmail.com>
- In-Reply-To
- <xmqqikgdxj93.fsf@gitster.g>
On Fri, Oct 17, 2025, at 6:20 PM, Junio C Hamano wrote:
Show 27 quoted lines
> "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.
Show 16 quoted lines
> 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.