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

> From: Julia Evans <julia@jvns.ca>
> 
> 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 <tree-ish>/<commit> 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 <julia@jvns.ca>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
> ---
>  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..71e8f52430 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 or the index to a known state
> 

> 
>  DESCRIPTION
>  -----------
> -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 last three forms, copy entries from _<tree-ish>_ to the index.
> +`git reset` does either of the following:
> +
> +1. `git reset [<mode>] <commit>` changes which commit HEAD points to. This