From: Julia Evans <julia@jvns.ca>
Date: Mon, 20 Oct 2025 19:03:39 GMT
Subject: Re: [PATCH 1/4] doc: git-reset: reorder the forms
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:
> "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.

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