Re: [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]`

> From: Julia Evans <julia@jvns.ca>
> 
> From user feedback, there was some confusion about the differences
> between the modes, including:
> 
> 1. Sometimes it says "index" and sometimes "index file".
>    Fix by replacing "index file" with "index".
> 2. Many comments about not being able to understand what `--merge` does.
>    Fix by mentioning obscure situations, since that seems to be what
>    it's for. Most folks will use `git <cmd> --abort`.
> 3. Issues telling the difference between --soft and --mixed, as well as
>    --keep. Leave --keep alone because I couldn't understand its use case,
>    but change `--soft` / `--mixed` / `--hard` as follows:
> 
> --mixed is the default, so put it first.
> 
> Describe --soft/--mixed/--hard with the following structure:
> 
> * Start by saying what happens to the files in the working directory,
>   because the thing users want to avoid most is irretrievably losing
>   changes to their working directory files.
> * Then describe what happens to the staging area. Right now it seems to
>   frame leaving the index alone as being a sort of neutral action.
>   I think this is part of what's confusing users, because in Git when
>   you update HEAD, Git almost always updates the index to match HEAD.
>   So leaving the index unchanged while updating HEAD is actually quite
>   unusual, and it deserves to be flagged.
> * Finally, give an example for --soft to explain a common use case.
> 
> 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 | 44 ++++++++++++++++++++----------------
>  1 file changed, 24 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
> index 71e8f52430..6de0d524c3 100644
> --- a/Documentation/git-reset.adoc
> +++ b/Documentation/git-reset.adoc
> @@ -24,42 +24,46 @@ DESCRIPTION
>     the staged version of the specified files.
> 
>  `git reset [<mode>] [<commit>]`::
> -	This form resets the current branch head to _<commit>_ and
> -	possibly updates the index (resetting it to the tree of _<commit>_) 

> ++
> +The _<mode>_ must be one of the following (default `--mixed`):
>  +
> ---
> -`--soft`::
> -	Does not touch the index file or the working tree at all (but
> -	resets the head to _<commit>_, just like all modes do). This leaves
> -	all your changed files "Changes to be committed", as `git status`
> -	would put it.
> 
> +--
>  `--mixed`::
> -	Resets the index but not the working tree (i.e., the changed files
> -	are preserved but not marked for commit) and reports what has not
> -	been updated. This is the default action.
> +	Leaves your working directory unchanged.
> +	Updates the index to match the new HEAD, so nothing will be staged.

>  +
>  If `-N` is specified, removed paths are marked as intent-to-add (see
>  linkgit:git-add[1]).
> 
> +`--soft`::
> +	Leave your working tree files and the index unchanged.
> +	For example, if you have no staged changes, you can use
> +	`git reset --soft HEAD~5; git commit`
> +	to combine the last 5 commits into 1 commit. This works even with
> +	changes in the working tree, which are left untouched, but such 

>  	which have not been added).
>  	If a file that is different between _<commit>_ and the index has
>  	unstaged changes, reset is aborted.
> -+
> -In other words, `--merge` does something like a `git read-tree -u -m