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

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

Changes in v4:
- Adjust wording per Jean-Noël Avila's review

Changes in v3:
- Adjust "git reset -p" description per Junio's review

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/
v2: https://lore.kernel.org/git/cover.1766103827.git.ben.knoble+github@gmail.com/
v3: https://lore.kernel.org/git/cover.1767307382.git.ben.knoble+github@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 | 111 ++++++++++++++++++-----------------
 1 file changed, 57 insertions(+), 54 deletions(-)

Diff-intervalle contre v3 :
1:  a558c5a868 = 1:  a558c5a868 doc: git-reset: reorder the forms
2:  f90be8559f ! 2:  3fc46c7158 doc: git-reset: clarify intro
    @@ Documentation/git-reset.adoc: git-reset(1)
      NAME
      ----
     -git-reset - Reset current HEAD to the specified state
    -+git-reset - Set HEAD or the index to a known state
    ++git-reset - Set `HEAD` or the index to a known state
      
      SYNOPSIS
      --------
    @@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
     -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
    -+   it possible to undo various Git operations, for example commit, merge,
    ++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.
3:  89c87c14aa ! 3:  0ca9fcf943 doc: git-reset: clarify `git reset [mode]`
    @@ Documentation/git-reset.adoc: DESCRIPTION
     -	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.
    ++	Leave your working directory unchanged.
    ++	Update 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
    +-If `-N` is specified, removed paths are marked as intent-to-add (see
    ++If `-N` is specified, mark removed paths as intent-to-add (see
      linkgit:git-add[1]).
      
     +`--soft`::
    @@ Documentation/git-reset.adoc: DESCRIPTION
     -	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>_,
    ++	Overwrite all files and directories with the version from _<commit>_,
     +	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.
    ++	Update the index to match the new `HEAD`, so nothing will be staged.
      
      `--merge`::
    -+	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
    +-	Resets the index and updates the files in the working tree that are
    +-	different between _<commit>_ and `HEAD`, but keeps those which are
    ++	Reset the index and update the files in the working tree that are
    ++	different between _<commit>_ and `HEAD`, but keep those which are
      	different between the index and working tree (i.e. which have changes
      	which have not been added).
    ++	Mainly exists to reset unmerged index entries, like those left behind by
    ++	`git am -3` or `git switch -m` in certain situations.
      	If a file that is different between _<commit>_ and the index has
      	unstaged changes, reset is aborted.
     -+
4:  96566265d8 ! 4:  accf7a0673 doc: git-reset: clarify `git reset <pathspec>`
    @@ 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.
    -+In this mode, `git reset` updates only the index (without updating the HEAD or
    ++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].
      

base-commit: f229982df19c327876ce7ded40f6efefe20da5d4