[PATCH v4 1/4] doc: git-reset: reorder the forms
From: D. Ben Knoble <hidden>
Date: 2026-01-05 21:48:59
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
From: Julia Evans <redacted>
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 <redacted>
Signed-off-by: Junio C Hamano <redacted>
Signed-off-by: D. Ben Knoble <redacted>
---
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