From: "D. Ben Knoble" <ben.knoble+github@gmail•com>
To: git@vger•kernel.org
Cc: "D. Ben Knoble" <ben.knoble+github@gmail•com>,
"Julia Evans" <julia@jvns•ca>,
"Jean-Noël Avila" <jn.avila@free•fr>
Subject: [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section
Date: Mon, 5 Jan 2026 16:48:14 -0500 [thread overview]
Message-ID: <cover.1767649692.git.ben.knoble+github@gmail.com> (raw)
In-Reply-To: <cover.1767307382.git.ben.knoble+github@gmail.com>
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
--
2.52.0.rc0.426.g1df11fb20d.dirty
next prev parent reply other threads:[~2026-01-05 21:48 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-17 20:05 [PATCH 0/4] doc: git-reset: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-17 20:05 ` [PATCH 1/4] doc: git-reset: reorder the forms Julia Evans via GitGitGadget
2025-10-17 22:20 ` Junio C Hamano
2025-10-20 19:03 ` Julia Evans
2025-10-17 20:05 ` [PATCH 2/4] doc: git-reset: clarify intro Julia Evans via GitGitGadget
2025-10-17 22:32 ` Junio C Hamano
2025-10-20 19:29 ` Julia Evans
2025-10-20 20:00 ` Junio C Hamano
2025-10-20 20:30 ` D. Ben Knoble
2025-12-03 18:15 ` Julia Evans
2025-10-17 20:05 ` [PATCH 3/4] doc: git-reset: clarify `git reset [mode]` Julia Evans via GitGitGadget
2025-10-18 4:53 ` Junio C Hamano
2025-10-20 20:23 ` Julia Evans
2025-10-20 20:33 ` D. Ben Knoble
2025-10-20 20:44 ` Junio C Hamano
2025-10-17 20:05 ` [PATCH 4/4] doc: git-reset: clarify `git reset <pathspec>` Julia Evans via GitGitGadget
2025-10-17 23:25 ` Junio C Hamano
2025-10-18 14:06 ` Ben Knoble
2025-10-18 16:17 ` Junio C Hamano
2025-12-19 0:23 ` [PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 2/4] doc: git-reset: clarify intro D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2025-12-30 5:23 ` Junio C Hamano
2026-01-01 22:32 ` D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-02 13:49 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-02 14:28 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-05 21:48 ` D. Ben Knoble [this message]
2026-01-05 21:48 ` [PATCH v4 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-07 3:55 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1767649692.git.ben.knoble+github@gmail.com \
--to=ben.knoble+github@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=jn.avila@free$(echo .)fr \
--cc=julia@jvns$(echo .)ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox