[PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section

["D. Ben Knoble" <ben.knoble+github@gmail.com>]

This continues Julia Evans's excellent work updating the git-reset docs.

Changes in v2:
- Mostly address Junio's review while keeping to Julia's style (?),
  taking at a stab at a few gray areas.
- I left alone the first patch, the commented-upon part of which is
  later rewritten anyway.

v1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset

Julia Evans (4):
  doc: git-reset: reorder the forms
  doc: git-reset: clarify intro
  doc: git-reset: clarify `git reset [mode]`
  doc: git-reset: clarify `git reset <pathspec>`

 Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 51 deletions(-)

Diff-intervalle contre v1 :
1:  5074fbf4ea ! 1:  a558c5a868 doc: git-reset: reorder the forms
    @@ Metadata
      ## Commit message ##
         doc: git-reset: reorder the forms
     
    -    >From user feedback: three users commented that the `git reset [mode]`
    +    From user feedback: three users commented that the `git reset [mode]`
         form is the one that they primarily use, and that they were suprised to
         see it listed last.
         ("I've never used git reset in any mode other than --hard").
2:  c7049edf39 ! 2:  f90be8559f doc: git-reset: clarify intro
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify intro
     
    -    >From user feedback, there were several points of confusion:
    +    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
    @@ Documentation/git-reset.adoc: git-reset(1)
      NAME
      ----
     -git-reset - Reset current HEAD to the specified state
    -+git-reset - Set HEAD to point at the specified commit
    ++git-reset - Set HEAD or the index to a known state
      
      SYNOPSIS
      --------
    @@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
     -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 [<mode>] <commit>` changes which commit HEAD points to.
    -+This makes it possible to undo various Git operations, for example
    -+commit, merge, rebase, and pull.
    ++`git reset` does either of the following:
     +
    -+However, when you specify files or directories or pass `--patch`,
    -+`git reset` will instead update the staged version of the specified
    -+files without updating HEAD.
    ++1. `git reset [<mode>] <commit>` changes which commit HEAD points to. This makes
    ++   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
3:  84aed17da6 ! 3:  89c87c14aa doc: git-reset: clarify `git reset [mode]`
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify `git reset [mode]`
     
    -    >From user feedback, there was some confusion about the differences
    +    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 `git merge --abort` since my best guess is that
    -       most folks want to use that instead of `git reset --merge`.
    +       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:
    @@ Commit message
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## Documentation/git-reset.adoc ##
    -@@ Documentation/git-reset.adoc: However, when you specify files or directories or pass `--patch`,
    - files without updating HEAD.
    +@@ Documentation/git-reset.adoc: DESCRIPTION
    +    the staged version of the specified files.
      
      `git reset [<mode>] [<commit>]`::
     -	This form resets the current branch head to _<commit>_ and
    @@ Documentation/git-reset.adoc: However, when you specify files or directories or
      linkgit:git-add[1]).
      
     +`--soft`::
    -+	Leaves your working directory unchanged. The index is left unchanged,
    -+	so everything in your current commit will be staged.
    ++	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.
    ++	to combine the last 5 commits into 1 commit. This works even with
    ++	changes in the working tree, which are left untouched, but such usage
    ++	can lead to confusion.
     +
      `--hard`::
     -	Resets the index and working tree. Any changes to tracked files in the
     -	working tree since _<commit>_ are discarded.  Any untracked files or
     -	directories in the way of writing any tracked files are simply deleted.
     +	Overwrites all files and directories with the version from _<commit>_,
    -+	and may overwrite untracked files.
    ++	and may overwrite untracked files. Tracked files not in _<commit>_ are
    ++	removed so that the working tree matches _<commit>_.
     +	Updates the index to match the new HEAD, so nothing will be staged.
      
      `--merge`::
    -+	Mainly exists for backwards compatibility: `git merge --abort` is the
    -+	usual way to abort a merge. See linkgit:git-merge[1] for the differences.
    ++	Mainly exists to reset unmerged index entries, like those left behind by
    ++	`git am -3` or `git switch -m` in certain situations.
      	Resets the index and updates the files in the working tree that are
      	different between _<commit>_ and `HEAD`, but keeps those which are
      	different between the index and working tree (i.e. which have changes
4:  0b9583f872 ! 4:  d6582dc53c doc: git-reset: clarify `git reset <pathspec>`
    @@ Metadata
      ## Commit message ##
         doc: git-reset: clarify `git reset <pathspec>`
     
    -    >From user feedback:
    +    From user feedback:
     
         - Continued confusion about the terms "tree-ish" and "pathspec"
         - The word "hunks" is confusing folks, use "changes" instead.
    @@ Documentation/git-reset.adoc: linkgit:git-add[1]).
     -and specifying a commit with `--source`, you
     -can copy the contents of a path out of a commit to the index and to the
     -working tree in one go.
    -+`git reset` only modifies the index: use linkgit:git-restore[1] instead
    -+if you'd like to also update the file in your working directory.
    ++In this mode, `git reset` updates only the index (without updating the HEAD or
    ++working tree files). If you want to update the files as well as the index
    ++entries, use linkgit:git-restore[1].
      
      `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
     -	Interactively select hunks in the difference between the index
    @@ Documentation/git-reset.adoc: linkgit:git-add[1]).
     -	in reverse to the index.
     +	Interactively select changes from the difference between the index
     +	and the specified commit or tree (which defaults to `HEAD`).
    -+	The chosen changes are unstaged.
    ++	The chosen changes are added to the index.
      +
      This means that `git reset -p` is the opposite of `git add -p`, i.e.
     -you can use it to selectively reset hunks. See the "Interactive Mode"
-- 
2.52.0.rc0.365.g9bf09b728d.dirty