doc: git-reset: clarify DESCRIPTION section

From: Julia Evans <[email protected]>

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 <[email protected]>

---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

Documentation/git-reset.adoc +8 -5

index 9843682e81..876187dc83 100644
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD to point at the specified commit
 
 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 [<mode>] <commit>` changes which commit HEAD points to.
+This makes it possible to undo various Git operations, for example
+commit, merge, rebase, and pull.
+
+However, when you specify files or directories or pass `--patch`,
+`git reset` will instead update the staged version of the specified
+files without updating HEAD.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and

Signature · 1 line

gitgitgadget

Junio C Hamano

2025-10-17 22:32 UTC #5 lore raw

Re: [PATCH 2/4] doc: git-reset: clarify intro

Quoted 36 lines · Julia Evans via GitGitGadget

From: Julia Evans <[email protected]>
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 <[email protected]>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
Documentation/git-reset.adoc +0 -0
index 9843682e81..876187dc83 100644

Documentation/git-reset.adoc git-reset(1) · line 6

Quoted 5 lines

Documentation/git-reset.adoc +1 -1

@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD to point at the specified commit

The command has dual-purpose, and it is a bit disturbing that the other one is not even mentioned in the original or in the updated text. "The other three forms" is about resetting the index without moving HEAD at all. Would this work better, I wonder?

Reset HEAD or index back to a known state

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 20

Quoted 3 lines

Documentation/git-reset.adoc +3 -0

+`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.

Good. These are prime examples of when resetting to a known state is useful.

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 24

Quoted 3 lines

Documentation/git-reset.adoc +3 -0

+However, when you specify files or directories or pass `--patch`,
+`git reset` will instead update the staged version of the specified
+files without updating HEAD.

I see no however here.

Other forms are not about flipping HEAD to any state we used to have before. Instead, they are about populating index entries from the state taken from an arbitrary tree-ish.

You can view them as enhanced variants of "git reset --mixed HEAD" (read it as "unstage all changes"). They are enhanced in the sense that unlike "git reset --mixed HEAD", the treeish the index entries are taken from does not have to be HEAD, and also in the sense that unlike "git reset --mixed HEAD", you can limit the index entries to be affected to a subset of paths. I am not sure it would make it easier to understand to explain them in terms of "reset --mixed HEAD" but I am reasonably sure that it would appear confusing until a reader realizes that the command has two very disinct mode, one that is primarily about HEAD, the other that is primarily about index.

Quoted 2 lines

git reset [<mode>] [<commit>]::
This form resets the current branch head to _<commit>_ and

Julia Evans

2025-10-20 19:29 UTC #6 lore raw

Re: [PATCH 2/4] doc: git-reset: clarify intro

Quoted 49 lines · Junio C Hamano

Quoted 36 lines · Julia Evans via GitGitGadget
From: Julia Evans <[email protected]>
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 <[email protected]>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
Documentation/git-reset.adoc +0 -0
index 9843682e81..876187dc83 100644
Documentation/git-reset.adoc git-reset(1) · line 6
Quoted 5 lines
Documentation/git-reset.adoc +1 -1
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD to point at the specified commit
The command has dual-purpose, and it is a bit disturbing that the other one is not even mentioned in the original or in the updated text. "The other three forms" is about resetting the index without moving HEAD at all. Would this work better, I wonder?

Quoted 1 line

Reset HEAD or index back to a known state

That's true, though I think we should avoid using "Reset" to explain what git reset does. Perhaps

Set HEAD or the index to a previous state

Quoted 17 lines

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 20
Quoted 3 lines
Documentation/git-reset.adoc +3 -0
+`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.
Good. These are prime examples of when resetting to a known state is useful.
Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 24
Quoted 3 lines
Documentation/git-reset.adoc +3 -0
+However, when you specify files or directories or pass `--patch`,
+`git reset` will instead update the staged version of the specified
+files without updating HEAD.
I see no however here.
Other forms are not about flipping HEAD to any state we used to have before. Instead, they are about populating index entries from the state taken from an arbitrary tree-ish.

Quoted 13 lines

You can view them as enhanced variants of "git reset --mixed HEAD" (read it as "unstage all changes"). They are enhanced in the sense that unlike "git reset --mixed HEAD", the treeish the index entries are taken from does not have to be HEAD, and also in the sense that unlike "git reset --mixed HEAD", you can limit the index entries to be affected to a subset of paths. I am not sure it would make it easier to understand to explain them in terms of "reset --mixed HEAD" but I am reasonably sure that it would appear confusing until a reader realizes that the command has two very disinct mode, one that is primarily about HEAD, the other that is primarily about index.
Quoted 2 lines
git reset [<mode>] [<commit>]::
This form resets the current branch head to _<commit>_ and

I agree that "git reset has two very distinct modes' is important. Here's an idea for how to communicate that.
It doesn't fully capture all of the nuances of git reset's command line syntax, but maybe that's not the job of the intro sentence anyway.

I don't love the use of "things" in "two things" but it would be weird to say "modes" because we already use "mode" to mean something else, and I haven't thought of something better yet.

git reset does two things:

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, it updates the staged version of the specified files.

Junio C Hamano

2025-10-20 20:00 UTC #7 lore raw

Re: [PATCH 2/4] doc: git-reset: clarify intro

Quoted 6 lines · Julia Evans

Quoted 1 line
Reset HEAD or index back to a known state
That's true, though I think we should avoid using "Reset" to explain what git reset does. Perhaps
Set HEAD or the index to a previous state

OK, though the state is not necessarily "previous".

Quoted 10 lines

I agree that "git reset has two very distinct modes' is important. Here's an idea for how to communicate that.
It doesn't fully capture all of the nuances of git reset's command line syntax, but maybe that's not the job of the intro sentence anyway.
I don't love the use of "things" in "two things" but it would be weird to say "modes" because we already use "mode" to mean something else, and I haven't thought of something better yet.
git reset does two things:

I do not mind "things", as long as it is not mislead readers into thinking that it may do two things at the same time. "modes" avoids that problem, as "you use it one way, and it does one thing, and you use it another way, and it does a very different thing" is the natural implication of that word.

"The command can be used in two ways"? "can be used for two different purposes?" I dunno.

D. Ben Knoble

2025-10-20 20:30 UTC #8 lore raw

Re: [PATCH 2/4] doc: git-reset: clarify intro

Quoted 13 lines · Junio C Hamano

Quoted 10 lines · Julia Evans
I agree that "git reset has two very distinct modes' is important. Here's an idea for how to communicate that.
It doesn't fully capture all of the nuances of git reset's command line syntax, but maybe that's not the job of the intro sentence anyway.
I don't love the use of "things" in "two things" but it would be weird to say "modes" because we already use "mode" to mean something else, and I haven't thought of something better yet.
git reset does two things:

Quoted 8 lines

I do not mind "things", as long as it is not mislead readers into thinking that it may do two things at the same time. "modes" avoids that problem, as "you use it one way, and it does one thing, and you use it another way, and it does a very different thing" is the natural implication of that word.
"The command can be used in two ways"? "can be used for two different purposes?" I dunno.

Some options:

git reset does one of two different things

git reset can be used to accomplish either of the following:

Signature · 1 line

D. Ben Knoble

Julia Evans

2025-12-03 18:15 UTC #9 lore raw

Re: [PATCH 2/4] doc: git-reset: clarify intro

In reply to Julia Evans

I was hoping to be able to finish this, but I don't have funding to work on the Git docs (I imagine like everyone else who works on them! :) ) and the time I budgeted to do this work has run out for now.

It's been really interesting to get to dig into the Git documentation and I really appreciate all of the reviews & encouragement along the way.

all the best,
Julia

Quoted 104 lines · Julia Evans

Quoted 49 lines · Junio C Hamano
Quoted 36 lines · Julia Evans via GitGitGadget
From: Julia Evans <[email protected]>
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 <[email protected]>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
Documentation/git-reset.adoc +0 -0
index 9843682e81..876187dc83 100644
Documentation/git-reset.adoc git-reset(1) · line 6
Quoted 5 lines
Documentation/git-reset.adoc +1 -1
@@ -3,7 +3,7 @@ git-reset(1)
 
 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD to point at the specified commit
The command has dual-purpose, and it is a bit disturbing that the other one is not even mentioned in the original or in the updated text. "The other three forms" is about resetting the index without moving HEAD at all. Would this work better, I wonder?
Quoted 1 line
Reset HEAD or index back to a known state
That's true, though I think we should avoid using "Reset" to explain what git reset does. Perhaps
Set HEAD or the index to a previous state
Quoted 17 lines
Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 20
Quoted 3 lines
Documentation/git-reset.adoc +3 -0
+`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.
Good. These are prime examples of when resetting to a known state is useful.
Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 24
Quoted 3 lines
Documentation/git-reset.adoc +3 -0
+However, when you specify files or directories or pass `--patch`,
+`git reset` will instead update the staged version of the specified
+files without updating HEAD.
I see no however here.
Other forms are not about flipping HEAD to any state we used to have before. Instead, they are about populating index entries from the state taken from an arbitrary tree-ish.
Quoted 13 lines
You can view them as enhanced variants of "git reset --mixed HEAD" (read it as "unstage all changes"). They are enhanced in the sense that unlike "git reset --mixed HEAD", the treeish the index entries are taken from does not have to be HEAD, and also in the sense that unlike "git reset --mixed HEAD", you can limit the index entries to be affected to a subset of paths. I am not sure it would make it easier to understand to explain them in terms of "reset --mixed HEAD" but I am reasonably sure that it would appear confusing until a reader realizes that the command has two very disinct mode, one that is primarily about HEAD, the other that is primarily about index.
Quoted 2 lines
git reset [<mode>] [<commit>]::
This form resets the current branch head to _<commit>_ and
I agree that "git reset has two very distinct modes' is important. Here's an idea for how to communicate that.
It doesn't fully capture all of the nuances of git reset's command line syntax, but maybe that's not the job of the intro sentence anyway.
I don't love the use of "things" in "two things" but it would be weird to say "modes" because we already use "mode" to mean something else, and I haven't thought of something better yet.
git reset does two things:
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, it updates the staged version of the specified files.

Julia Evans via GitGitGadget

author

2025-10-17 20:06 UTC #10 lore raw

PATCH 3/4 doc: git-reset: clarify `git reset [mode]`

From: Julia Evans <[email protected]>

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 <[email protected]>

---
 Documentation/git-reset.adoc | 42 +++++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 20 deletions(-)

Documentation/git-reset.adoc +22 ~~-20~~

index 876187dc83..fa4bb2b551 100644
@@ -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

Signature · 1 line

gitgitgadget

Junio C Hamano

2025-10-18 04:53 UTC #11 lore raw

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 45

Quoted 2 lines · Julia Evans via GitGitGadget

+--soft::
Documentation/git-reset.adoc +1 -0
+	Leaves your working directory unchanged. The index is left unchanged,

Why not "leave your working tree files and the index unchanged"?

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 46

Quoted 1 line

Documentation/git-reset.adoc +1 -0
+	so everything in your current commit will be staged.

Hmph, if a reader still has the "stage the changes" mental model, then this would be true only when you are resetting to HEAD~1 (this is one of the reasons why I am hesitant to overuse the verb "stage"). If you are going to HEAD~5, such a reader would say that the changes made by the past 5 commits are staged, not just the commit you are on before resetting.

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 49

Quoted 3 lines

Documentation/git-reset.adoc +3 -0

+	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.

Another thing that may be worth mentioning is that you can do this even with local changes in the working tree, because you do not give "-a" to the final "git commit".

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 54

Quoted 7 lines

--hard::

Documentation/git-reset.adoc +3 -3

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

One thing that may be worth saying is that the paths in the working tree that are tracked in the index that are not in <commit> will disappear.

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 58

Quoted 3 lines

--merge::

Documentation/git-reset.adoc +2 -0

+	Mainly exists for backwards compatibility: `git merge --abort` is the
+	usual way to abort a merge. See linkgit:git-merge[1] for the differences.

There are operations that are not "git merge" that can leave the index in an unmerged state, and you do not want to use "git merge --abort" to get out of such a state, I would imagine. So I have a feeling that we are better off without these two lines.

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 62

Quoted 9 lines

Documentation/git-reset.adoc +0 -3

 	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.

I do not mind losing this. Unlike the time back when these two lines were written, nobody knows (and more importantly, nobody has to know) what "read-tree -u -m" does, these days.

Quoted 2 lines

--keep::
Resets index entries and updates files in the working tree that are

Thanks.

Julia Evans

2025-10-20 20:24 UTC #12 lore raw

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

Quoted 6 lines · Junio C Hamano

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 45
Quoted 2 lines · Julia Evans via GitGitGadget
+--soft::
Documentation/git-reset.adoc +1 -0
+	Leaves your working directory unchanged. The index is left unchanged,
Why not "leave your working tree files and the index unchanged"?

The reason I say "working directory" instead of "working tree" is that I've seen a few comments from users saying that they don't know what "working tree" means. I'm still not sure what the reason for calling it a "working tree" is.

The reason for keeping them separate sentences is just for symmetry with the other commands, and also because (like I mentioned in the commit message) "leaving X and Y unchanged" makes it sound like leaving X and Y unchanged is a "neutral operation", while actually leaving the index unchanged while updating HEAD is actually a fairly weird thing to do.

Quoted 8 lines

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 46
Quoted 1 line
Documentation/git-reset.adoc +1 -0
+	so everything in your current commit will be staged.
Hmph, if a reader still has the "stage the changes" mental model, then this would be true only when you are resetting to HEAD~1 (this is one of the reasons why I am hesitant to overuse the verb "stage"). If you are going to HEAD~5, such a reader would say that the changes made by the past 5 commits are staged, not just the commit you are on before resetting.

That's fair. I'll try to think about whether there's a better way to say this.

Previously it said "This leaves all your changed files "Changes to be committed", as git status would put it.", which has the same issue ("changed files" since when exactly?).
Maybe I can fix this by being more explicit about which changes exactly will show up as "staged" in git status.

Quoted 7 lines

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 49
Quoted 3 lines
Documentation/git-reset.adoc +3 -0
+	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.
Another thing that may be worth mentioning is that you can do this even with local changes in the working tree, because you do not give "-a" to the final "git commit".

Maybe! I'm not sure if we want to encourage doing complex Git operations with unstaged changes though. I feel like it often leads to suffering and I think people who want to do that can already infer that it's possible.

Quoted 11 lines

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 54
Quoted 7 lines
--hard::
Documentation/git-reset.adoc +3 -3
-	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.
One thing that may be worth saying is that the paths in the working tree that are tracked in the index that are not in <commit> will disappear.

Interesting, I don't think I knew that. Would this be a more accurate description of what git reset --hard does, conceptually? I want to make sure I understand how it works.

1. List every file that's either in the target commit or in the index
2. For each file, make it match the target commit (overwriting untracked files if necessary)

Quoted 8 lines

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 58
Quoted 3 lines
--merge::
Documentation/git-reset.adoc +2 -0
+	Mainly exists for backwards compatibility: `git merge --abort` is the
+	usual way to abort a merge. See linkgit:git-merge[1] for the differences.
There are operations that are not "git merge" that can leave the index in an unmerged state, and you do not want to use "git merge --abort" to get out of such a state, I would imagine. So I have a feeling that we are better off without these two lines.

Do you mean git reset and git cherry-pick, or are there other operations that can leave the operation in an unmerged state?
My mental model is that if there's a merge conflict, the best way to deal with it is to use the appropriate --abort command (depending on how you got there), because the command-specific --abort will know how to do things like restore autostashed changes. But I agree that just saying "use git merge --abort is not a complete description.

Quoted 5 lines

Documentation/git-reset.adoc +0 -0

 	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

Quoted 8 lines

Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 62
Quoted 4 lines
Documentation/git-reset.adoc +0 -3
 	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.
I do not mind losing this. Unlike the time back when these two lines were written, nobody knows (and more importantly, nobody has to know) what "read-tree -u -m" does, these days.

Thanks, it's useful for me to know more about the context at the time this was written.

D. Ben Knoble

2025-10-20 20:33 UTC #13 lore raw

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

Quoted 7 lines · Julia Evans

Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Julia Evans via GitGitGadget
+--soft::
+ Leaves your working directory unchanged. The index is left unchanged,

Quoted 6 lines

Quoted 1 line
Why not "leave your working tree files and the index unchanged"?
The reason I say "working directory" instead of "working tree" is that I've seen a few comments from users saying that they don't know what "working tree" means. I'm still not sure what the reason for calling it a "working tree" is.

At a guess: suppose I have a non-bare repository ~/code/git with corresponding ~/code/git/.git directory, but PWD=~/code/git/t. Then my working directory is "…/t" but my working tree includes all the stuff Git is tracking above me, too! (It also helps draw parallelism with git-worktree, but that's a bit circular.)

Junio C Hamano

2025-10-20 20:44 UTC #14 lore raw

Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

In reply to Julia Evans

Quoted 8 lines · Julia Evans

Quoted 6 lines · Junio C Hamano
Documentation/git-reset.adoc However, when you specify files or directories or pass `--patch`, · line 45
Quoted 2 lines · Julia Evans via GitGitGadget
+--soft::
Documentation/git-reset.adoc +1 -0
+	Leaves your working directory unchanged. The index is left unchanged,
Why not "leave your working tree files and the index unchanged"?

Quoted 4 lines

The reason I say "working directory" instead of "working tree" is that I've seen a few comments from users saying that they don't know what "working tree" means. I'm still not sure what the reason for calling it a "working tree" is.

"working tree" refers to the directory that is the top level of a checkout; I'd view (current) "working directory" can be anything $(pwd), that may be outside control of any git repository, and that is why I tend to avoid the latter when I want to be more precise (and "worktree" is another thing---used to refer to one particular "working tree" among other working trees attached to the same repository).

But that distinction was not the part I wanted to comment on. The question was about two sentences talking about two things separately. IOW

Leave your working directory and the index unchanged.

is what I would have expected, and I was wondering why they are treated separately. After all, the index is part of your working tree state.

Quoted 5 lines

The reason for keeping them separate sentences is just for symmetry with the other commands, and also because (like I mentioned in the commit message) "leaving X and Y unchanged" makes it sound like leaving X and Y unchanged is a "neutral operation", while actually leaving the index unchanged while updating HEAD is actually a fairly weird thing to do.

Sorry, but I do not understand this comment.

The index and the HEAD are two different things, and it is natural that they can move independently. After all we update the former without updating the latter all the time (it is called "git add").

Besides, the two things the --soft does not touch are the files in the working tree and the index. The index has what you want to make the next commit out of, and the working tree has the state that may come after that state in the index. Keeping both of them intact when moving HEAD around is one natural thing to do when you want to squash the previous N commits after "git add <paths>" by doing "git reset --soft HEAD~N && git commit". Contrasting to that, "--mixed" would leave the files in the working tree intact, while matching the index to the HEAD you are moving to, essentially undoing your "git add"s before you decided to reset. That's another natural thing to do when you decide to keep the clean slate and rebuild your index from scratch to prepare for a commit that comes on top of the commit you are moving to.

So, no, I do not understand the above comment.

Quoted 2 lines

Do you mean git reset and git cherry-pick, or are there other operations that can leave the operation in an unmerged state?

There are many commands that leaves the index unmerged, like "am -3", "rebase", "switch -m", "stash pop", etc.

Julia Evans via GitGitGadget

author

2025-10-17 20:06 UTC #15 lore raw

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

From: Julia Evans <[email protected]>

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 <[email protected]>

---
 Documentation/git-reset.adoc | 27 +++++++++++----------------
 1 file changed, 11 insertions(+), 16 deletions(-)

Documentation/git-reset.adoc +11 ~~-16~~

index fa4bb2b551..52d380a756 100644
@@ -79,29 +79,24 @@ 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.
+`git reset` only modifies the index: use linkgit:git-restore[1] instead
+if you'd like to also update the file in your working directory.
 
 `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 chosen changes are unstaged.
 +
 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.

Signature · 1 line

gitgitgadget

Junio C Hamano

2025-10-17 23:25 UTC #16 lore raw

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

Quoted 2 lines · Julia Evans via GitGitGadget

+git reset only modifies the index: use linkgit:git-restore[1] instead +if you'd like to also update the file in your working directory.

I cannot judge if it is clear enough with the above sentence that we are only talking about "the other forms", but if that is the case and it is clear we are not talking about the mode where the command repoints HEAD to another commit, the above is a good piece of advice.

If not, perhaps

When specified what paths to modify, 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 git-restore.

may be a way to clarify the distinction between two modes.

Documentation/git-reset.adoc linkgit:git-add[1]). · line 99

Quoted 13 lines

git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::

Documentation/git-reset.adoc +5 -5

-	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 chosen changes are unstaged.
 +
 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.

I do not see a good reason why we avoid saying the noun "patch", especially when we see it in the option. If we were allowed to say "patch" here, "changes from the difference between ..." can be rephrased to "parts of the patch that makes the index match the specified commit", which may be simpler.

Also "unstaged" is only true when <tree-ish> is "HEAD". If you are grabbing the contents recorded in a different commit and shoving them into the index, that is not "unstaging" at all. Rather, if you are planning to make a commit out of the index after doing so, that is rather "staging" a change! While the verb "to (un)stage" may have been a useful tool to explain the act of updating index entries to describe its effect relative to what is in HEAD, in this particular case, it is probably more confusing than illuninating to use it.

Ben Knoble

2025-10-18 14:06 UTC #17 lore raw

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

Quoted 16 lines · Junio C Hamano

Quoted 11 lines · "Julia Evans via GitGitGadget
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
Documentation/git-reset.adoc +4 -3
-    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 chosen changes are unstaged.
+
This means that git reset -p is the opposite of git add -p, i.e.
Documentation/git-reset.adoc +0 -2
-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.

Quoted 8 lines

Documentation/git-reset.adoc linkgit:git-add[1]). · line 99
Quoted 2 lines
Documentation/git-reset.adoc +2 -0
+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.
I do not see a good reason why we avoid saying the noun "patch", especially when we see it in the option. If we were allowed to say "patch" here, "changes from the difference between ..." can be rephrased to "parts of the patch that makes the index match the specified commit", which may be simpler.

I think the issue was the word « hunk », not « patch ».

Junio C Hamano

2025-10-18 16:17 UTC #18 lore raw

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

Quoted 24 lines · Ben Knoble

Quoted 15 lines · Junio C Hamano
Quoted 11 lines · "Julia Evans via GitGitGadget
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
Documentation/git-reset.adoc +4 -3
-    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 chosen changes are unstaged.
+
This means that git reset -p is the opposite of git add -p, i.e.
Documentation/git-reset.adoc +0 -2
-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.
Quoted 8 lines
Documentation/git-reset.adoc linkgit:git-add[1]). · line 99
Quoted 2 lines
Documentation/git-reset.adoc +2 -0
+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.
I do not see a good reason why we avoid saying the noun "patch", especially when we see it in the option. If we were allowed to say "patch" here, "changes from the difference between ..." can be rephrased to "parts of the patch that makes the index match the specified commit", which may be simpler.

Quoted 1 line

I think the issue was the word « hunk », not « patch ».

I know. That is exactly where my question comes from.

D. Ben Knoble

2025-12-19 00:24 UTC #19 lore raw

v2 cover doc: git-reset: clarify DESCRIPTION section

This continues Julia Evans's excellent work updating the git-reset docs.

Changes in v2:
- Mostly address Junio's review while keeping to Julia's style (?), taking at a stab at a few gray areas.
- I left alone the first patch, the commented-upon part of which is later rewritten anyway.

v1: https://lore.kernel.org/git/[email protected]/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset

Julia Evans (4):
doc: git-reset: reorder the forms
doc: git-reset: clarify intro
doc: git-reset: clarify git reset [mode]
doc: git-reset: clarify git reset <pathspec>

 Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 51 deletions(-)

Diff-intervalle contre v1 :
1: 5074fbf4ea ! 1: a558c5a868 doc: git-reset: reorder the forms
@@ Metadata
## Commit message ##
doc: git-reset: reorder the forms

- >From user feedback: three users commented that the git reset [mode]
+ 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").
2: c7049edf39 ! 2: f90be8559f doc: git-reset: clarify intro
@@ Metadata
## Commit message ##
doc: git-reset: clarify intro

- >From user feedback, there were several points of confusion:
+ 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
@@ Documentation/git-reset.adoc: git-reset(1)
NAME
----
-git-reset - Reset current HEAD to the specified state
-+git-reset - Set HEAD to point at the specified commit ++git-reset - Set HEAD or the index to a known state

SYNOPSIS
--------
@@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
-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 [<mode>] <commit> changes which commit HEAD points to. -+This makes it possible to undo various Git operations, for example -+commit, merge, rebase, and pull.
++git reset does either of the following:
+
-+However, when you specify files or directories or pass --patch, -+git reset will instead update the staged version of the specified -+files without updating HEAD.
++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
3: 84aed17da6 ! 3: 89c87c14aa doc: git-reset: clarify git reset [mode]
@@ Metadata
## Commit message ##
doc: git-reset: clarify git reset [mode]

- >From user feedback, there was some confusion about the differences
+ 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.
+ Fix by mentioning obscure situations, since that seems to be what
+ it's for. Most folks will use git <cmd> --abort.
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:
@@ Commit message

## Documentation/git-reset.adoc ##
-@@ Documentation/git-reset.adoc: However, when you specify files or directories or pass --patch,
- files without updating HEAD.
+@@ Documentation/git-reset.adoc: DESCRIPTION
+ the staged version of the specified files.

git reset [<mode>] [<commit>]::
- This form resets the current branch head to _<commit>_ and
@@ Documentation/git-reset.adoc: However, when you specify files or directories or
linkgit:git-add[1]).

+--soft::
-+ Leaves your working directory unchanged. The index is left unchanged,
-+ so everything in your current commit will be staged.
++ Leave your working tree files and the index unchanged.
+ 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.
++ to combine the last 5 commits into 1 commit. This works even with
++ changes in the working tree, which are left untouched, but such usage
++ can lead to confusion.
+
--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.
++ and may overwrite untracked files. Tracked files not in _<commit>_ are
++ removed so that the working tree matches _<commit>_.
+ 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.
++ Mainly exists to reset unmerged index entries, like those left behind by
++ git am -3 or git switch -m in certain situations.
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
4: 0b9583f872 ! 4: d6582dc53c doc: git-reset: clarify git reset <pathspec>
@@ Metadata
## Commit message ##
doc: git-reset: clarify git reset <pathspec>

- >From user feedback:
+ From user feedback:

- Continued confusion about the terms "tree-ish" and "pathspec"
- The word "hunks" is confusing folks, use "changes" instead.
@@ Documentation/git-reset.adoc: linkgit:git-add[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 only modifies the index: use linkgit:git-restore[1] instead -+if you'd like to also update the file in your working directory. ++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
@@ Documentation/git-reset.adoc: linkgit:git-add[1]).
- 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 chosen changes are unstaged.
++ The chosen changes are added 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"

Signature · 1 line

2.52.0.rc0.365.g9bf09b728d.dirty

D. Ben Knoble

2025-12-19 00:24 UTC #20 lore raw

PATCH v2 1/4 doc: git-reset: reorder the forms

From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

Documentation/git-reset.adoc +29 ~~-29~~

index 3b9ba9aee9..9843682e81 100644
@@ -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.

Signature · 1 line

2.52.0.rc0.365.g9bf09b728d.dirty

D. Ben Knoble

2025-12-19 00:24 UTC #21 lore raw

PATCH v2 2/4 doc: git-reset: clarify intro

From: Julia Evans <[email protected]>

From user feedback, there were several points of confusion:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

Documentation/git-reset.adoc +8 -5

index 9843682e81..71e8f52430 100644
@@ -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

Signature · 1 line

2.52.0.rc0.365.g9bf09b728d.dirty

D. Ben Knoble

2025-12-19 00:24 UTC #22 lore raw

PATCH v2 3/4 doc: git-reset: clarify `git reset [mode]`

From: Julia Evans <[email protected]>

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 obscure situations, since that seems to be what it's for. Most folks will use git <cmd> --abort.
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:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)

Documentation/git-reset.adoc +24 ~~-20~~

index 71e8f52430..6de0d524c3 100644
@@ -24,42 +24,46 @@ DESCRIPTION
    the staged version of the specified files.
 
 `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`::
+	Leave your working tree files and the index unchanged.
+	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. This works even with
+	changes in the working tree, which are left untouched, but such usage
+	can lead to confusion.
+
 `--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. Tracked files not in _<commit>_ are
+	removed so that the working tree matches _<commit>_.
+	Updates the index to match the new HEAD, so nothing will be staged.
 
 `--merge`::
+	Mainly exists to reset unmerged index entries, like those left behind by
+	`git am -3` or `git switch -m` in certain situations.
 	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

Signature · 1 line

2.52.0.rc0.365.g9bf09b728d.dirty

D. Ben Knoble

2025-12-19 00:24 UTC #23 lore raw

PATCH v2 4/4 doc: git-reset: clarify `git reset <pathspec>`

From: Julia Evans <[email protected]>

From user feedback:

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

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

Documentation/git-reset.adoc +12 ~~-16~~

index 6de0d524c3..ab7f565286 100644
@@ -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 chosen changes are added 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.
+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.

Signature · 1 line

2.52.0.rc0.365.g9bf09b728d.dirty

Junio C Hamano

2025-12-30 05:23 UTC #24 lore raw

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

Documentation/git-reset.adoc linkgit:git-add[1]). · line 98

Quoted 7 lines · D. Ben Knoble

git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::

Documentation/git-reset.adoc +3 -3

-	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 chosen changes are added to the index.

The previous iteration said "changes are unstaged", implying that the changes are removed from the index. But now it says the changes are added to the index. Which one?

I think neither is correct. I wasn't involved in the design of the behaviour of "reset -p", but IIUC,

git reset -p
git reset -p HEAD

show "git diff --cached HEAD" (i.e., what damage you will cause if you commit what is in the index), so chosen hunks will be reverted out of the index if you say "y" to "reset -p" prompt.

On the other hand,

git reset -p COMMIT

for COMMIT that is not HEAD gives "git diff -R --cached COMMIT" (i.e., the changes to take you closer to the named commit), so chosen hunks will participate in the next commit if you commit after completing this "reset -p" session.

The contents in the index are modified using the chosen hunks.

is the best description I can come up with.

The actual prompt asks "unstage this hunk?" when operating against HEAD, while the prompt changes to "apply this hunk to index?" when opeating against a commit that is not HEAD, so it might be simpler not to say anything about the direction of the application (i.e., how the chosen hunks are used to modify the index) in this paragraph, like the above example, may be a viable option.

D. Ben Knoble

2026-01-01 22:32 UTC #25 lore raw

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

Quoted 11 lines · Junio C Hamano

Documentation/git-reset.adoc linkgit:git-add[1]). · line 98
Quoted 7 lines · D. Ben Knoble
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
Documentation/git-reset.adoc +3 -3
-     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 chosen changes are added to the index.

Quoted 3 lines

The previous iteration said "changes are unstaged", implying that the changes are removed from the index. But now it says the changes are added to the index. Which one?

Ah, I think I really mean that _changes_ are added. The change might be an addition (+) or subtraction (-) in patch terms, so some changes may result in the index having fewer modifications relative to the working tree or something. But it's not
very clear, and certainly a bit pedantic.

Quoted 9 lines

I think neither is correct. I wasn't involved in the design of the behaviour of "reset -p", but IIUC,
git reset -p
git reset -p HEAD
show "git diff --cached HEAD" (i.e., what damage you will cause if you commit what is in the index), so chosen hunks will be reverted out of the index if you say "y" to "reset -p" prompt.

Indeed. I was actually expecting to see the reverse hunks here, so I was surprised to see the staged hunks.

Quoted 8 lines

On the other hand,
git reset -p COMMIT
for COMMIT that is not HEAD gives "git diff -R --cached COMMIT" (i.e., the changes to take you closer to the named commit), so chosen hunks will participate in the next commit if you commit after completing this "reset -p" session.

Hm. I can see how this behaves nearly the opposite of the former. Yikes.

Quoted 10 lines

The contents in the index are modified using the chosen hunks.
is the best description I can come up with.
The actual prompt asks "unstage this hunk?" when operating against HEAD, while the prompt changes to "apply this hunk to index?" when opeating against a commit that is not HEAD, so it might be simpler not to say anything about the direction of the application (i.e., how the chosen hunks are used to modify the index) in this paragraph, like the above example, may be a viable option.

Yeah, I think so. Will send a new version with this update.

D. Ben Knoble

2026-01-01 22:44 UTC #26 lore raw

v3 cover doc: git-reset: clarify DESCRIPTION section

This continues Julia Evans's excellent work updating the git-reset docs.

Changes in v3:
- Adjust "git reset -p" description per Junio's review

v1: https://lore.kernel.org/git/[email protected]/
v2: https://lore.kernel.org/git/[email protected]/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset
Generated-with: git format-patch -v3 [email protected] --range-diff=d6582dc53ca852ef01421d2dd2c446dadb731dad~4..d6582dc53ca852ef01421d2dd2c446dadb731dad -o PATCHES origin.. --cc 'Julia Evans <[email protected]>'

Julia Evans (4):
doc: git-reset: reorder the forms
doc: git-reset: clarify intro
doc: git-reset: clarify git reset [mode]
doc: git-reset: clarify git reset <pathspec>

 Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------
 1 file changed, 54 insertions(+), 51 deletions(-)

Diff-intervalle contre v2 :

1:  a558c5a868 = 1:  a558c5a868 doc: git-reset: reorder the forms
2:  f90be8559f = 2:  f90be8559f doc: git-reset: clarify intro
3:  89c87c14aa = 3:  89c87c14aa doc: git-reset: clarify `git reset [mode]`
4:  d6582dc53c ! 4:  96566265d8 doc: git-reset: clarify `git reset <pathspec>`

@@ Documentation/git-reset.adoc: linkgit:git-add[1]).
- 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 chosen changes are added to the index.
++ 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"

base-commit: f229982df19c327876ce7ded40f6efefe20da5d4

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-01 22:44 UTC #27 lore raw

PATCH v3 1/4 doc: git-reset: reorder the forms

From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

Documentation/git-reset.adoc +29 ~~-29~~

index 3b9ba9aee9..9843682e81 100644
@@ -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.

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-01 22:44 UTC #28 lore raw

PATCH v3 2/4 doc: git-reset: clarify intro

From: Julia Evans <[email protected]>

From user feedback, there were several points of confusion:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

Documentation/git-reset.adoc +8 -5

index 9843682e81..71e8f52430 100644
@@ -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

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

Jean-Noël AVILA

2026-01-02 13:56 UTC #29 lore raw

Re: [PATCH v3 2/4] doc: git-reset: clarify intro

Documentation/git-reset.adoc git-reset(1)

Quoted 38 lines · Le jeudi 1 janvier 2026, 23:43:57 heure normale d’Europe centrale D. Ben…

From: Julia Evans <[email protected]>
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 <[email protected]>
Signed-off-by Junio C Hamano <[email protected]>
Signed-off-by D. Ben Knoble <[email protected]>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
Documentation/git-reset.adoc +0 -0
index 9843682e81..71e8f52430 100644
@@ -3,7 +3,7 @@ git-reset(1)

There are HEAD that passed through the style checks.

Documentation/git-reset.adoc git-reset(1) · line 7

Quoted 6 lines

Documentation/git-reset.adoc +1 -1

 NAME
 ----
-git-reset - Reset current HEAD to the specified state
+git-reset - Set HEAD or the index to a known state

Here

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--]

Quoted 3 lines

Documentation/git-reset.adoc +0 -0

 SYNOPSIS
 --------

@@ -15,10 +15,13 @@ git reset (--patch | -p) [<tree-ish>] [--]

[<pathspec>...]

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]

Quoted 10 lines

Documentation/git-reset.adoc +3 -4

 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

And here.

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]

Quoted 3 lines

Documentation/git-reset.adoc +3 -0

+   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

Documentation/git-reset.adoc git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...] · line 27

Quoted 4 lines

Documentation/git-reset.adoc +1 -0

+   the staged version of the specified files.
 
 `git reset [<mode>] [<commit>]`::
 	This form resets the current branch head to _<commit>_ and

Thanks

D. Ben Knoble

2026-01-01 22:44 UTC #30 lore raw

PATCH v3 3/4 doc: git-reset: clarify `git reset [mode]`

From: Julia Evans <[email protected]>

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 obscure situations, since that seems to be what it's for. Most folks will use git <cmd> --abort.
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:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)

Documentation/git-reset.adoc +24 ~~-20~~

index 71e8f52430..6de0d524c3 100644
@@ -24,42 +24,46 @@ DESCRIPTION
    the staged version of the specified files.
 
 `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`::
+	Leave your working tree files and the index unchanged.
+	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. This works even with
+	changes in the working tree, which are left untouched, but such usage
+	can lead to confusion.
+
 `--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. Tracked files not in _<commit>_ are
+	removed so that the working tree matches _<commit>_.
+	Updates the index to match the new HEAD, so nothing will be staged.
 
 `--merge`::
+	Mainly exists to reset unmerged index entries, like those left behind by
+	`git am -3` or `git switch -m` in certain situations.
 	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

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

Jean-Noël AVILA

2026-01-02 14:28 UTC #31 lore raw

Re: [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]`

Quoted 41 lines · On Thursday, 1 January 2026 23:43:58 CET D. Ben Knoble wrote:

From: Julia Evans <[email protected]>
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 obscure situations, since that seems to be what it's for. Most folks will use git <cmd> --abort.
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 <[email protected]>
Signed-off-by Junio C Hamano <[email protected]>
Signed-off-by D. Ben Knoble <[email protected]>
---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)
Documentation/git-reset.adoc +0 -0
index 71e8f52430..6de0d524c3 100644

Documentation/git-reset.adoc DESCRIPTION · line 28

Quoted 5 lines

Documentation/git-reset.adoc +0 -2

@@ -24,42 +24,46 @@ DESCRIPTION
    the staged version of the specified files.
 
 `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

Documentation/git-reset.adoc DESCRIPTION · line 29

Quoted 1 line

Documentation/git-reset.adoc +0 -1
-	the working tree depending on _<mode>_. Before the operation, 

ORIG_HEAD

Documentation/git-reset.adoc DESCRIPTION

Quoted 4 lines

Documentation/git-reset.adoc +2 -2

-	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

Documentation/git-reset.adoc DESCRIPTION

Quoted 3 lines

Documentation/git-reset.adoc +3 -0

+	to match the contents of _<commit>_.
+	_<commit>_ defaults to `HEAD`.
+	Before the operation, `ORIG_HEAD` is set to the tip of the current

branch.

Quoted 7 lines

Documentation/git-reset.adoc +2 -4

++
+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

Documentation/git-reset.adoc DESCRIPTION · line 39

Quoted 10 lines

Documentation/git-reset.adoc +3 -5

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

Please use imperative mood here, and use HEAD.

Documentation/git-reset.adoc DESCRIPTION

Quoted 10 lines

Documentation/git-reset.adoc +6 -0

 +
 If `-N` is specified, removed paths are marked as intent-to-add (see
 linkgit:git-add[1]).
 
+`--soft`::
+	Leave your working tree files and the index unchanged.
+	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. This works even with
+	changes in the working tree, which are left untouched, but such

usage

Documentation/git-reset.adoc DESCRIPTION

Quoted 4 lines

Documentation/git-reset.adoc +2 -1

+	can lead to confusion.
+
 `--hard`::
-	Resets the index and working tree. Any changes to tracked files in

the

Documentation/git-reset.adoc DESCRIPTION · line 51

Quoted 2 lines

Documentation/git-reset.adoc +0 -2

-	working tree since _<commit>_ are discarded.  Any untracked files or
-	directories in the way of writing any tracked files are simply

deleted.

Documentation/git-reset.adoc DESCRIPTION · line 53

Quoted 1 line

Documentation/git-reset.adoc +1 -0
+	Overwrites all files and directories with the version from 

_<commit>_,

Documentation/git-reset.adoc DESCRIPTION · line 54

Quoted 1 line

Documentation/git-reset.adoc +1 -0

+	and may overwrite untracked files. Tracked files not in _<commit>_

are

Documentation/git-reset.adoc DESCRIPTION · line 56

Quoted 2 lines

Documentation/git-reset.adoc +2 -0

+	removed so that the working tree matches _<commit>_.
+	Updates the index to match the new HEAD, so nothing will be staged.

Here too.

Documentation/git-reset.adoc DESCRIPTION · line 58

Quoted 3 lines

Documentation/git-reset.adoc +1 -0

 `--merge`::
+	Mainly exists to reset unmerged index entries, like those left

behind by

Documentation/git-reset.adoc DESCRIPTION · line 60

Quoted 1 line

Documentation/git-reset.adoc +1 -0
+	`git am -3` or `git switch -m` in certain situations.

Personal preference, please insert this context sentence after the main description of the action. Could you also change the mood of the description to imperative?

Documentation/git-reset.adoc DESCRIPTION

Quoted 3 lines

Documentation/git-reset.adoc +0 -0

 	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

Documentation/git-reset.adoc DESCRIPTION

Quoted 5 lines

Documentation/git-reset.adoc +0 -2

 	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>`,

Documentation/git-reset.adoc DESCRIPTION · line 69

Quoted 4 lines

Documentation/git-reset.adoc +0 -1

-but carries forward unmerged index entries.
 
 `--keep`::
 	Resets index entries and updates files in the working tree that are

Thanks

D. Ben Knoble

2026-01-01 22:44 UTC #32 lore raw

PATCH v3 4/4 doc: git-reset: clarify `git reset <pathspec>`

From: Julia Evans <[email protected]>

From user feedback:

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

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

Documentation/git-reset.adoc +12 ~~-16~~

index 6de0d524c3..770f08c7f8 100644
@@ -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.

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-05 21:48 UTC #33 lore raw

v4 cover doc: git-reset: clarify DESCRIPTION section

This continues Julia Evans's excellent work updating the git-reset docs.

Changes in v4:
- Adjust wording per Jean-Noël Avila's review

Changes in v3:
- Adjust "git reset -p" description per Junio's review

v1: https://lore.kernel.org/git/[email protected]/
v2: https://lore.kernel.org/git/[email protected]/
v3: https://lore.kernel.org/git/[email protected]/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset

Julia Evans (4):
doc: git-reset: reorder the forms
doc: git-reset: clarify intro
doc: git-reset: clarify git reset [mode]
doc: git-reset: clarify git reset <pathspec>

 Documentation/git-reset.adoc | 111 ++++++++++++++++++-----------------
 1 file changed, 57 insertions(+), 54 deletions(-)

Diff-intervalle contre v3 :

1:  a558c5a868 = 1:  a558c5a868 doc: git-reset: reorder the forms
2:  f90be8559f ! 2:  3fc46c7158 doc: git-reset: clarify intro

@@ Documentation/git-reset.adoc: git-reset(1)
NAME
----
-git-reset - Reset current HEAD to the specified state
-+git-reset - Set HEAD or the index to a known state ++git-reset - Set HEAD or the index to a known state

SYNOPSIS
--------
@@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
-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,
++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.
3: 89c87c14aa ! 3: 0ca9fcf943 doc: git-reset: clarify git reset [mode]
@@ Documentation/git-reset.adoc: DESCRIPTION
- 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.
++ Leave your working directory unchanged.
++ Update 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 +-If -N is specified, removed paths are marked as intent-to-add (see ++If -N is specified, mark removed paths as intent-to-add (see linkgit:git-add[1]).

+--soft::
@@ Documentation/git-reset.adoc: DESCRIPTION
- 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>_,
++ Overwrite all files and directories with the version from _<commit>_,
+ and may overwrite untracked files. Tracked files not in _<commit>_ are
+ removed so that the working tree matches _<commit>_.
-+ Updates the index to match the new HEAD, so nothing will be staged.
++ Update the index to match the new HEAD, so nothing will be staged.

--merge::
-+ Mainly exists to reset unmerged index entries, like those left behind by
-+ git am -3 or git switch -m in certain situations.
- Resets the index and updates the files in the working tree that are
- different between _<commit>_ and HEAD, but keeps those which are
+- Resets the index and updates the files in the working tree that are
+- different between _<commit>_ and HEAD, but keeps those which are
++ Reset the index and update the files in the working tree that are
++ different between _<commit>_ and HEAD, but keep those which are
different between the index and working tree (i.e. which have changes which have not been added).
++ Mainly exists to reset unmerged index entries, like those left behind by
++ git am -3 or git switch -m in certain situations.
If a file that is different between _<commit>_ and the index has unstaged changes, reset is aborted.
-+
4: 96566265d8 ! 4: accf7a0673 doc: git-reset: clarify git reset <pathspec>
@@ Documentation/git-reset.adoc: linkgit:git-add[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 ++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].

base-commit: f229982df19c327876ce7ded40f6efefe20da5d4

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-05 21:48 UTC #34 lore raw

PATCH v4 1/4 doc: git-reset: reorder the forms

From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

Documentation/git-reset.adoc +29 ~~-29~~

index 3b9ba9aee9..9843682e81 100644
@@ -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.

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-05 21:49 UTC #35 lore raw

PATCH v4 2/4 doc: git-reset: clarify intro

From: Julia Evans <[email protected]>

From user feedback, there were several points of confusion:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

Documentation/git-reset.adoc +8 -5

index 9843682e81..91dc6e6278 100644
@@ -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

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-05 21:49 UTC #36 lore raw

PATCH v4 3/4 doc: git-reset: clarify `git reset [mode]`

From: Julia Evans <[email protected]>

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 obscure situations, since that seems to be what it's for. Most folks will use git <cmd> --abort.
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:

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 50 +++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 23 deletions(-)

Documentation/git-reset.adoc +27 ~~-23~~

index 91dc6e6278..37c868ae24 100644
@@ -24,42 +24,46 @@ DESCRIPTION
    the staged version of the specified files.
 
 `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.
+	Leave your working directory unchanged.
+	Update 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
+If `-N` is specified, mark removed paths as intent-to-add (see
 linkgit:git-add[1]).
 
+`--soft`::
+	Leave your working tree files and the index unchanged.
+	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. This works even with
+	changes in the working tree, which are left untouched, but such usage
+	can lead to confusion.
+
 `--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.
+	Overwrite all files and directories with the version from _<commit>_,
+	and may overwrite untracked files. Tracked files not in _<commit>_ are
+	removed so that the working tree matches _<commit>_.
+	Update the index to match the new `HEAD`, so nothing will be staged.
 
 `--merge`::
-	Resets the index and updates the files in the working tree that are
-	different between _<commit>_ and `HEAD`, but keeps those which are
+	Reset the index and update the files in the working tree that are
+	different between _<commit>_ and `HEAD`, but keep those which are
 	different between the index and working tree (i.e. which have changes
 	which have not been added).
+	Mainly exists to reset unmerged index entries, like those left behind by
+	`git am -3` or `git switch -m` in certain situations.
 	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

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

D. Ben Knoble

2026-01-05 21:49 UTC #37 lore raw

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

From: Julia Evans <[email protected]>

From user feedback:

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

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

Documentation/git-reset.adoc +12 ~~-16~~

index 37c868ae24..5023b50699 100644
@@ -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.

Signature · 1 line

2.52.0.rc0.426.g1df11fb20d.dirty

Junio C Hamano

2026-01-07 03:55 UTC #38 lore raw