From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Fri, 02 Jan 2026 13:49:45 GMT
Subject: Re: [PATCH v3 2/4] doc: git-reset: clarify intro
Message-ID: <5953760.DvuYhMxLoT@piment-oiseau>
In-Reply-To: <f90be8559f7d1d8362077a6f888687ee8be063b4.1767307382.git.ben.knoble+github@gmail.com>

Le jeudi 1 janvier 2026, 23:43:57 heure normale d’Europe centrale D. Ben 
Knoble a écrit :
> 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)

There are `HEAD` that passed through the style checks.

> 
>  NAME
>  ----
> -git-reset - Reset current HEAD to the specified state
> +git-reset - Set HEAD or the index to a known state
> 

Here

>  SYNOPSIS
>  --------
> @@ -15,10 +15,13 @@ git reset (--patch | -p) [<tree-ish>] [--] 
[<pathspec>...]
> 
>  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 
makes

And here.

> +   it possible to undo various Git operations, for example commit, merge,
> +   rebase, and pull.
> +2. When you specify files or directories or pass `--patch`, `git reset` 
updates
> +   the staged version of the specified files.
> 
>  `git reset [<mode>] [<commit>]`::
>  	This form resets the current branch head to _<commit>_ and

Thanks