From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 17 Oct 2025 22:20:56 GMT
Subject: Re: [PATCH 1/4] doc: git-reset: reorder the forms
Message-ID: <xmqqikgdxj93.fsf@gitster.g>
In-Reply-To: <c7e1c090475f76d94363018681c34f3955abe87e.1760731558.git.gitgitgadget@gmail.com>

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