patch, 4 partsdoc: git-reset: clarify DESCRIPTION section

I got feedback from 24 Git users about the current git reset man page, using this tool: https://text-feedback.wizardzines.com/git-reset.

My main goals here are to highlight the git reset [--soft | --hard | --mixed...] <commit> use of git reset that many users commenting said they considered the "main" use (which is currently at the end), explain how --soft, --hard and --mixed work more clearly, and to avoid using terminology that users don't understand when that's realistic.

Like we discussed with git checkout, there's some tension about using the word "index" since on one hand many users don't know what it means, but on the other hand (especially with commands like git reset --hard) it gets very awkward to talk about what's going on precisely without using that word, since the index is a core concept in Git's data model. I've done my best here to use the word "index" where I think it's appropriate and use the word "staged" otherwise.

There were also quite a few comments about the EXAMPLES section which I think could also be made clearer, but I'll defer that to a separate patch series to keep the size of this one under control.

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 | 102 +++++++++++++++++------------------
 1 file changed, 51 insertions(+), 51 deletions(-)

base-commit: a483264b01b977f3e65a4419103c21e6af7412a2
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1991%2Fjvns%2Fclarify-reset-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1991/jvns/clarify-reset-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1991

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]` form is the one that they primarily use, and that they were suprised to see it listed last. ("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what "Reset current HEAD to the specified state" at the beginning refers to, and because the `git reset [mode]` form is the only thing that `git reset` uniquely does, the others could also be done with `git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

In the original, the "defaults to HEAD in all forms" did make sense, but as the new text does not mention there are three other forms like the original did, that sentence was made harder to fathom. I can accept that you do not want to get ahead of yourself to explain "copy from <treeish>" before you are ready to talk more about these other forms, but we'd at least need to acknowledge that what we want to refer to when we say "all forms" here. Perhaps

    Among the four forms, the first form sets the current branch
    head to ....  In all forms, the tree-ish/commit defaults to
    HEAD.

is easier to read?

Or "The other three forms copy entries ..."?

Other than that, looks good to me.

On Fri, Oct 17, 2025, at 6:20 PM, Junio C Hamano wrote:

That's true. I didn't pay very careful attention to the text here because I completely rewrote it in a later patch anyway. I'll make it say something that makes more sense.

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action it does as "Reset ...", commands should not use their name to describe themselves, and that the word "mode" is used to mean several different things on this page.

Address these by being more clear about two use cases for `git reset` ("to undo operations" and "to update staged files"), and explaining what the conditions are for each case instead of forcing the user to figure out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

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

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.

On Fri, Oct 17, 2025, at 6:32 PM, Junio C Hamano wrote:

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

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" <julia@jvns.ca> writes:

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

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.

On Mon, Oct 20, 2025 at 4:02 PM Junio C Hamano <gitster@pobox.com> wrote:

Some options:

    `git reset` does one of two different things

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

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

On Mon, Oct 20, 2025, at 3:29 PM, Julia Evans wrote:

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning `git merge --abort` since my best guess is that
   most folks want to use that instead of `git reset --merge`.
3. Issues telling the difference between --soft and --mixed, as well as
   --keep. Leave --keep alone because I couldn't understand its use case,
   but change `--soft` / `--mixed` / `--hard` as follows:

--mixed is the default, so put it first.

Describe --soft/--mixed/--hard with the following structure:

* Start by saying what happens to the files in the working directory,
  because the thing users want to avoid most is irretrievably losing
  changes to their working directory files.
* Then describe what happens to the staging area. Right now it seems to
  frame leaving the index alone as being a sort of neutral action.
  I think this is part of what's confusing users, because in Git when
  you update HEAD, Git almost always updates the index to match HEAD.
  So leaving the index unchanged while updating HEAD is actually quite
  unusual, and it deserves to be flagged.
* Finally, give an example for --soft to explain a common use case.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 42 +++++++++++++++++++-----------------
 1 file changed, 22 insertions(+), 20 deletions(-)

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

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.

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

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.

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.

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.

On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:

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.

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

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.

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)

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.

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

On Mon, Oct 20, 2025 at 4:28 PM Julia Evans <julia@jvns.ca> wrote:

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

"Julia Evans" <julia@jvns.ca> writes:

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

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.

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

From: Julia Evans <julia@jvns.ca>

From user feedback:

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
 Documentation/git-reset.adoc | 27 +++++++++++----------------
 1 file changed, 11 insertions(+), 16 deletions(-)

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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.

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.

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

Ben Knoble <ben.knoble@gmail.com> writes:

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

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/pull.1991.git.1760731558.gitgitgadget@gmail.com/
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
         Signed-off-by: Junio C Hamano <gitster@pobox.com>
     
      ## 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"

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]` form is the one that they primarily use, and that they were suprised to see it listed last. ("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what "Reset current HEAD to the specified state" at the beginning refers to, and because the `git reset [mode]` form is the only thing that `git reset` uniquely does, the others could also be done with `git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action it does as "Reset ...", commands should not use their name to describe themselves, and that the word "mode" is used to mean several different things on this page.

Address these by being more clear about two use cases for `git reset` ("to undo operations" and "to update staged files"), and explaining what the conditions are for each case instead of forcing the user to figure out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning 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 <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback:

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

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.

On Tue, Dec 30, 2025 at 12:23 AM Junio C Hamano <gitster@pobox.com> wrote:

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.

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

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

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

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

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

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/pull.1991.git.1760731558.gitgitgadget@gmail.com/
v2: https://lore.kernel.org/git/cover.1766103827.git.ben.knoble+github@gmail.com/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset
Generated-with: git format-patch -v3 --in-reply-to=cover.1766103827.git.ben.knoble+github@gmail.com --range-diff=d6582dc53ca852ef01421d2dd2c446dadb731dad~4..d6582dc53ca852ef01421d2dd2c446dadb731dad -o PATCHES origin.. --cc 'Julia Evans <julia@jvns.ca>'

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

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]` form is the one that they primarily use, and that they were suprised to see it listed last. ("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what "Reset current HEAD to the specified state" at the beginning refers to, and because the `git reset [mode]` form is the only thing that `git reset` uniquely does, the others could also be done with `git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action it does as "Reset ...", commands should not use their name to describe themselves, and that the word "mode" is used to mean several different things on this page.

Address these by being more clear about two use cases for `git reset` ("to undo operations" and "to update staged files"), and explaining what the conditions are for each case instead of forcing the user to figure out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

Le jeudi 1 janvier 2026, 23:43:57 heure normale d’Europe centrale D. Ben Knoble a écrit :

There are `HEAD` that passed through the style checks.

Here

[<pathspec>...]

makes

And here.

updates

Thanks

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning 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 <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 20 deletions(-)

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

and

`ORIG_HEAD`

index

branch.

Please use imperative mood here, and use `HEAD`.

usage

the

deleted.

_<commit>_,

are

Here too.

behind by

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?

changes

<commit>`,

Thanks

From: Julia Evans <julia@jvns.ca>

From user feedback:

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

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

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/pull.1991.git.1760731558.gitgitgadget@gmail.com/
v2: https://lore.kernel.org/git/cover.1766103827.git.ben.knoble+github@gmail.com/
v3: https://lore.kernel.org/git/cover.1767307382.git.ben.knoble+github@gmail.com/
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

From: Julia Evans <julia@jvns.ca>

From user feedback: three users commented that the `git reset [mode]` form is the one that they primarily use, and that they were suprised to see it listed last. ("I've never used git reset in any mode other than --hard").

Move it to be first, since the `git reset [mode]` form is what "Reset current HEAD to the specified state" at the beginning refers to, and because the `git reset [mode]` form is the only thing that `git reset` uniquely does, the others could also be done with `git restore`.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback, there were several points of confusion:

- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
  ("I have no clue what the index is", "I've been using git for 20 years
  and still don't know what a tree-ish is"). Avoid using these terms
  where it makes sense.
- What "optionally modifying index and working tree to match" means
  ("to match what?" "optionally based on what?")
  Remove this from the intro, we can say it later when giving more
  details.
- One user suggested that "The <tree-ish>/<commit> defaults to HEAD
  in all forms." should be repeated later on, since it's easy to miss.
  Instead say that HEAD is the default in each case later.

Another issue is that `git reset` consistently describes the action it does as "Reset ...", commands should not use their name to describe themselves, and that the word "mode" is used to mean several different things on this page.

Address these by being more clear about two use cases for `git reset` ("to undo operations" and "to update staged files"), and explaining what the conditions are for each case instead of forcing the user to figure out the pattern is in first form vs the other 3 forms.

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback, there was some confusion about the differences between the modes, including:

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning 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 <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 50 +++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 23 deletions(-)

From: Julia Evans <julia@jvns.ca>

From user feedback:

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
 Documentation/git-reset.adoc | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

Looking good.  Shall we mark it for 'next'?