From: "D. Ben Knoble" <ben.knoble+github@gmail•com>
To: git@vger•kernel.org
Cc: "Julia Evans" <julia@jvns•ca>,
"Jean-Noël Avila" <jn.avila@free•fr>,
"Junio C Hamano" <gitster@pobox•com>,
"D. Ben Knoble" <ben.knoble+github@gmail•com>
Subject: [PATCH v4 1/4] doc: git-reset: reorder the forms
Date: Mon, 5 Jan 2026 16:48:15 -0500 [thread overview]
Message-ID: <a558c5a8684639a2e888866a650357f54f29f2a6.1767649692.git.ben.knoble+github@gmail.com> (raw)
In-Reply-To: <cover.1767649692.git.ben.knoble+github@gmail.com>
From: Julia Evans <julia@jvns•ca>
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").
Move it to be first, since the `git reset [mode]` form is what
"Reset current HEAD to the specified state" at the beginning refers
to, and because the `git reset [mode]` form is the only thing that
`git reset` uniquely does, the others could also be done with
`git restore`.
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 | 58 ++++++++++++++++++------------------
1 file changed, 29 insertions(+), 29 deletions(-)
diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 3b9ba9aee9..9843682e81 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
SYNOPSIS
--------
[synopsis]
+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
git reset [-q] [<tree-ish>] [--] <pathspec>...
git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
DESCRIPTION
-----------
-In the first three forms, copy entries from _<tree-ish>_ to the index.
-In the last form, set the current branch head (`HEAD`) to _<commit>_,
+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.
-
-`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
-`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
- These forms reset the index entries for all paths that match the
- _<pathspec>_ to their state at _<tree-ish>_. (It does not affect
- the working tree or the current branch.)
-+
-This means that `git reset <pathspec>` is the opposite of `git add
-<pathspec>`. This command is equivalent to
-`git restore [--source=<tree-ish>] --staged <pathspec>...`.
-+
-After running `git reset <pathspec>` to update the index entry, you can
-use linkgit:git-restore[1] to check the contents out of the index to
-the working tree. Alternatively, using linkgit:git-restore[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 (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
- Interactively select hunks in the difference between the index
- and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
- in reverse 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"
-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
+In the last three forms, copy entries from _<tree-ish>_ to the index.
`git reset [<mode>] [<commit>]`::
This form resets the current branch head to _<commit>_ and
@@ -98,6 +72,32 @@ but carries forward unmerged index entries.
the submodules' `HEAD` to be detached at that commit.
--
+`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
+`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
+ These forms reset the index entries for all paths that match the
+ _<pathspec>_ to their state at _<tree-ish>_. (It does not affect
+ the working tree or the current branch.)
++
+This means that `git reset <pathspec>` is the opposite of `git add
+<pathspec>`. This command is equivalent to
+`git restore [--source=<tree-ish>] --staged <pathspec>...`.
++
+After running `git reset <pathspec>` to update the index entry, you can
+use linkgit:git-restore[1] to check the contents out of the index to
+the working tree. Alternatively, using linkgit:git-restore[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 (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
+ Interactively select hunks in the difference between the index
+ and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
+ in reverse 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"
+section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
+
See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands.
--
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 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-05 21:48 ` D. Ben Knoble [this message]
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=a558c5a8684639a2e888866a650357f54f29f2a6.1767649692.git.ben.knoble+github@gmail.com \
--to=ben.knoble+github@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--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