[PATCH v4 4/4] doc: git-reset: clarify `git reset <pathspec>`

public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

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 4/4] doc: git-reset: clarify `git reset <pathspec>`
Date: Mon,  5 Jan 2026 16:48:18 -0500	[thread overview]
Message-ID: <accf7a0673358d4724e4944117a382494404deb1.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:

- Continued confusion about the terms "tree-ish" and "pathspec"
- The word "hunks" is confusing folks, use "changes" instead.
- On the part about `git restore`, there were a few comments to the
  effect of "wait, this doesn't actually update any files? What? Why?"
  Be more direct that `git reset` does not update files: there's no
  obvious reason to suggest that folks use `git reset` followed by `git
  restore`, instead suggest just using `git restore`.

Continue avoiding the use of the word "reset" to
describe what "git reset" does.

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 | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 37c868ae24..5023b50699 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -81,29 +81,25 @@ linkgit:git-add[1]).
 
 `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.)
+	For all specified files or directories, set the staged version to
+	the version from the given commit or tree (which defaults to `HEAD`).
 +
 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>...`.
+<pathspec>`: it unstages all changes to the specified file(s) or
+directories. This is equivalent to `git restore --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.
+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
-	and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
-	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 index is modified using the chosen changes.
 +
 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.
+you can use it to selectively unstage changes. See the "Interactive Mode"
+section of linkgit:git-add[1] to learn how to use the `--patch` option.
 
 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:49 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       ` [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       ` D. Ben Knoble [this message]
2026-01-07  3:55       ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section Junio C Hamano

find likely ancestor, descendant, or conflicting patches for this message:
( dfblob:37c868ae2 dfblob:5023b5069 )
 OR (
bs:"[PATCH v4 4/4] doc: git-reset: clarify `git reset <pathspec>`" )
	(help)

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=accf7a0673358d4724e4944117a382494404deb1.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