From: "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com>
To: git@vger•kernel.org
Cc: Julia Evans <julia@jvns•ca>, Julia Evans <julia@jvns•ca>
Subject: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`
Date: Fri, 17 Oct 2025 20:05:57 +0000 [thread overview]
Message-ID: <597ea0f5ce24967974358e18603265b14322ba54.1760731558.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1991.git.1760731558.gitgitgadget@gmail.com>
From: Julia Evans <julia@jvns•ca>
From user feedback, there was some confusion about the differences
between the modes, including:
1. Sometimes it says "index" and sometimes "index file".
Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
Fix by mentioning `git merge --abort` since my best guess is that
most folks want to use that instead of `git reset --merge`.
3. Issues telling the difference between --soft and --mixed, as well as
--keep. Leave --keep alone because I couldn't understand its use case,
but change `--soft` / `--mixed` / `--hard` as follows:
--mixed is the default, so put it first.
Describe --soft/--mixed/--hard with the following structure:
* Start by saying what happens to the files in the working directory,
because the thing users want to avoid most is irretrievably losing
changes to their working directory files.
* Then describe what happens to the staging area. Right now it seems to
frame leaving the index alone as being a sort of neutral action.
I think this is part of what's confusing users, because in Git when
you update HEAD, Git almost always updates the index to match HEAD.
So leaving the index unchanged while updating HEAD is actually quite
unusual, and it deserves to be flagged.
* Finally, give an example for --soft to explain a common use case.
Signed-off-by: Julia Evans <julia@jvns•ca>
---
Documentation/git-reset.adoc | 42 +++++++++++++++++++-----------------
1 file changed, 22 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
index 876187dc83..fa4bb2b551 100644
--- a/Documentation/git-reset.adoc
+++ b/Documentation/git-reset.adoc
@@ -24,42 +24,44 @@ However, when you specify files or directories or pass `--patch`,
files without updating HEAD.
`git reset [<mode>] [<commit>]`::
- This form resets the current branch head to _<commit>_ and
- possibly updates the index (resetting it to the tree of _<commit>_) and
- the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
- is set to the tip of the current branch. If _<mode>_ is omitted,
- defaults to `--mixed`. The _<mode>_ must be one of the following:
+ Set the current branch head (`HEAD`) to point at _<commit>_.
+ Depending on _<mode>_, also update the working directory and/or index
+ to match the contents of _<commit>_.
+ _<commit>_ defaults to `HEAD`.
+ Before the operation, `ORIG_HEAD` is set to the tip of the current branch.
++
+The _<mode>_ must be one of the following (default `--mixed`):
+
---
-`--soft`::
- Does not touch the index file or the working tree at all (but
- resets the head to _<commit>_, just like all modes do). This leaves
- all your changed files "Changes to be committed", as `git status`
- would put it.
+--
`--mixed`::
- 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.
+
If `-N` is specified, removed paths are marked as intent-to-add (see
linkgit:git-add[1]).
+`--soft`::
+ Leaves your working directory unchanged. The index is left unchanged,
+ so everything in your current commit will be staged.
+ For example, if you have no staged changes, you can use
+ `git reset --soft HEAD~5; git commit`
+ to combine the last 5 commits into 1 commit.
+
`--hard`::
- 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>_,
+ and may overwrite untracked files.
+ Updates the index to match the new HEAD, so nothing will be staged.
`--merge`::
+ Mainly exists for backwards compatibility: `git merge --abort` is the
+ usual way to abort a merge. See linkgit:git-merge[1] for the differences.
Resets the index and updates the files in the working tree that are
different between _<commit>_ and `HEAD`, but keeps those which are
different between the index and working tree (i.e. which have changes
which have not been added).
If a file that is different between _<commit>_ and the index has
unstaged changes, reset is aborted.
-+
-In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
-but carries forward unmerged index entries.
`--keep`::
Resets index entries and updates files in the working tree that are
--
gitgitgadget
next prev parent reply other threads:[~2025-10-17 20:06 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 ` Julia Evans via GitGitGadget [this message]
2025-10-18 4:53 ` [PATCH 3/4] doc: git-reset: clarify `git reset [mode]` 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 ` [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=597ea0f5ce24967974358e18603265b14322ba54.1760731558.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--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