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 2/4] doc: git-reset: clarify intro
Date: Mon, 5 Jan 2026 16:48:16 -0500 [thread overview]
Message-ID: <3fc46c7158fdfb5fea5616bebb713e564d843d8e.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, there were several points of confusion:
- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
("I have no clue what the index is", "I've been using git for 20 years
and still don't know what a tree-ish is"). Avoid using these terms
where it makes sense.
- What "optionally modifying index and working tree to match" means
("to match what?" "optionally based on what?")
Remove this from the intro, we can say it later when giving more
details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
in all forms." should be repeated later on, since it's easy to miss.
Instead say that HEAD is the default in each case later.
Another issue is that `git reset` consistently describes the action
it does as "Reset ...", commands should not use their name to describe
themselves, and that the word "mode" is used to mean several different
things on this page.
Address these by being more clear about two use cases for `git reset`
("to undo operations" and "to update staged files"), and explaining what
the conditions are for each case instead of forcing the user to figure
out the pattern is in first form vs the other 3 forms.
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 | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 9843682e81..91dc6e6278 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -3,7 +3,7 @@ git-reset(1)
NAME
----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set `HEAD` or the index to a known state
SYNOPSIS
--------
@@ -15,10 +15,13 @@ git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
DESCRIPTION
-----------
-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.
-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,
+ rebase, and pull.
+2. When you specify files or directories or pass `--patch`, `git reset` updates
+ the staged version of the specified files.
`git reset [<mode>] [<commit>]`::
This form resets the current branch head to _<commit>_ and
--
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 ` D. Ben Knoble [this message]
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=3fc46c7158fdfb5fea5616bebb713e564d843d8e.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