{"thread":{"id":"64347","subject":"[PATCH 0/4] doc: git-reset: clarify DESCRIPTION section","startedAt":"2025-10-17T20:06:00Z","lastAt":"2026-01-07T03:55:34Z","messageCount":39,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Ben Knoble","Julia Evans","D. Ben Knoble","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"529093","messageId":"pull.1991.git.1760731558.gitgitgadget@gmail.com","threadId":"64347","inReplyTo":null,"subject":"[PATCH 0/4] doc: git-reset: clarify DESCRIPTION section","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-17T20:05:54Z","receivedAt":"2025-10-17T20:06:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I got feedback from 24 Git users about the current git reset man page, using\nthis tool: https://text-feedback.wizardzines.com/git-reset.\n\nMy main goals here are to highlight the git reset [--soft | --hard |\n--mixed...] use of git reset that many users commenting said they\nconsidered the \"main\" use (which is currently at the end), explain how\n--soft, --hard and --mixed work more clearly, and to avoid using terminology\nthat users don't understand when that's realistic.\n\nLike we discussed with git checkout, there's some tension about using the\nword \"index\" since on one hand many users don't know what it means, but on\nthe other hand (especially with commands like git reset --hard) it gets very\nawkward to talk about what's going on precisely without using that word,\nsince the index is a core concept in Git's data model. I've done my best\nhere to use the word \"index\" where I think it's appropriate and use the word\n\"staged\" otherwise.\n\nThere were also quite a few comments about the EXAMPLES section which I\nthink could also be made clearer, but I'll defer that to a separate patch\nseries to keep the size of this one under control.\n\nJulia Evans (4):\n doc: git-reset: reorder the forms\n doc: git-reset: clarify intro\n doc: git-reset: clarify `git reset [mode]`\n doc: git-reset: clarify `git reset `\n\n Documentation/git-reset.adoc | 102 +++++++++++++++++------------------\n 1 file changed, 51 insertions(+), 51 deletions(-)\n\n\nbase-commit: a483264b01b977f3e65a4419103c21e6af7412a2\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1991%2Fjvns%2Fclarify-reset-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1991/jvns/clarify-reset-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1991\n-- \ngitgitgadget\n"},{"id":"529094","messageId":"c7e1c090475f76d94363018681c34f3955abe87e.1760731558.git.gitgitgadget@gmail.com","threadId":"64347","inReplyTo":"pull.1991.git.1760731558.gitgitgadget@gmail.com","subject":"[PATCH 1/4] doc: git-reset: reorder the forms","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-17T20:05:55Z","receivedAt":"2025-10-17T20:06:02Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: three users commented that the `git reset [mode]`\nform is the one that they primarily use, and that they were suprised to\nsee it listed last.\n(\"I've never used git reset in any mode other than --hard\").\n\nMove it to be first, since the `git reset [mode]` form is what\n\"Reset current HEAD to the specified state\" at the beginning refers\nto, and because the `git reset [mode]` form is the only thing that\n`git reset` uniquely does, the others could also be done with\n`git restore`.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------\n 1 file changed, 29 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 3b9ba9aee9..9843682e81 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n SYNOPSIS\n --------\n [synopsis]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n git reset [-q] [] [--] ...\n git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n git reset (--patch | -p) [] [--] [...]\n-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from __ to the index.\n-In the last form, set the current branch head (`HEAD`) to __,\n+In the first form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n The __/__ defaults to `HEAD` in all forms.\n-\n-`git reset [-q] [] [--] ...`::\n-`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n-+\n-This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n-+\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n-\n-`git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n-+\n-This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+In the last three forms, copy entries from __ to the index.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n@@ -98,6 +72,32 @@ but carries forward unmerged index entries.\n \tthe submodules' `HEAD` to be detached at that commit.\n --\n \n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n+\tThese forms reset the index entries for all paths that match the\n+\t__ to their state at __. (It does not affect\n+\tthe working tree or the current branch.)\n++\n+This means that `git reset ` is the opposite of `git add\n+`. This command is equivalent to\n+`git restore [--source=] --staged ...`.\n++\n+After running `git reset ` to update the index entry, you can\n+use linkgit:git-restore[1] to check the contents out of the index to\n+the working tree. Alternatively, using linkgit:git-restore[1]\n+and specifying a commit with `--source`, you\n+can copy the contents of a path out of a commit to the index and to the\n+working tree in one go.\n+\n+`git reset (--patch | -p) [] [--] [...]`::\n+\tInteractively select hunks in the difference between the index\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n+\tin reverse to the index.\n++\n+This means that `git reset -p` is the opposite of `git add -p`, i.e.\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-- \ngitgitgadget\n\n"},{"id":"529095","messageId":"6b5459b7ab478de33d17f9518906396f8a01e0d6.1760731558.git.gitgitgadget@gmail.com","threadId":"64347","inReplyTo":"pull.1991.git.1760731558.gitgitgadget@gmail.com","subject":"[PATCH 2/4] doc: git-reset: clarify intro","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-17T20:05:56Z","receivedAt":"2025-10-17T20:06:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there were several points of confusion:\n\n- What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n (\"I have no clue what the index is\", \"I've been using git for 20 years\n and still don't know what a tree-ish is\"). Avoid using these terms\n where it makes sense.\n- What \"optionally modifying index and working tree to match\" means\n (\"to match what?\" \"optionally based on what?\")\n Remove this from the intro, we can say it later when giving more\n details.\n- One user suggested that \"The / defaults to HEAD\n in all forms.\" should be repeated later on, since it's easy to miss.\n Instead say that HEAD is the default in each case later.\n\nAnother issue is that `git reset` consistently describes the action\nit does as \"Reset ...\", commands should not use their name to describe\nthemselves, and that the word \"mode\" is used to mean several different\nthings on this page.\n\nAddress these by being more clear about two use cases for `git reset`\n(\"to undo operations\" and \"to update staged files\"), and explaining what\nthe conditions are for each case instead of forcing the user to figure\nout the pattern is in first form vs the other 3 forms.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-reset.adoc | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 9843682e81..876187dc83 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -3,7 +3,7 @@ git-reset(1)\n \n NAME\n ----\n-git-reset - Reset current HEAD to the specified state\n+git-reset - Set HEAD to point at the specified commit\n \n SYNOPSIS\n --------\n@@ -15,10 +15,13 @@ git reset (--patch | -p) [] [--] [...]\n \n DESCRIPTION\n -----------\n-In the first form, set the current branch head (`HEAD`) to __,\n-optionally modifying index and working tree to match.\n-The __/__ defaults to `HEAD` in all forms.\n-In the last three forms, copy entries from __ to the index.\n+`git reset [] ` changes which commit HEAD points to.\n+This makes it possible to undo various Git operations, for example\n+commit, merge, rebase, and pull.\n+\n+However, when you specify files or directories or pass `--patch`,\n+`git reset` will instead update the staged version of the specified\n+files without updating HEAD.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n-- \ngitgitgadget\n\n"},{"id":"529097","messageId":"597ea0f5ce24967974358e18603265b14322ba54.1760731558.git.gitgitgadget@gmail.com","threadId":"64347","inReplyTo":"pull.1991.git.1760731558.gitgitgadget@gmail.com","subject":"[PATCH 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-17T20:05:57Z","receivedAt":"2025-10-17T20:06:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there was some confusion about the differences\nbetween the modes, including:\n\n1. Sometimes it says \"index\" and sometimes \"index file\".\n Fix by replacing \"index file\" with \"index\".\n2. Many comments about not being able to understand what `--merge` does.\n Fix by mentioning `git merge --abort` since my best guess is that\n most folks want to use that instead of `git reset --merge`.\n3. Issues telling the difference between --soft and --mixed, as well as\n --keep. Leave --keep alone because I couldn't understand its use case,\n but change `--soft` / `--mixed` / `--hard` as follows:\n\n--mixed is the default, so put it first.\n\nDescribe --soft/--mixed/--hard with the following structure:\n\n* Start by saying what happens to the files in the working directory,\n because the thing users want to avoid most is irretrievably losing\n changes to their working directory files.\n* Then describe what happens to the staging area. Right now it seems to\n frame leaving the index alone as being a sort of neutral action.\n I think this is part of what's confusing users, because in Git when\n you update HEAD, Git almost always updates the index to match HEAD.\n So leaving the index unchanged while updating HEAD is actually quite\n unusual, and it deserves to be flagged.\n* Finally, give an example for --soft to explain a common use case.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-reset.adoc | 42 +++++++++++++++++++-----------------\n 1 file changed, 22 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 876187dc83..fa4bb2b551 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -24,42 +24,44 @@ However, when you specify files or directories or pass `--patch`,\n files without updating HEAD.\n \n `git reset [] []`::\n-\tThis form resets the current branch head to __ and\n-\tpossibly updates the index (resetting it to the tree of __) and\n-\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If __ is omitted,\n-\tdefaults to `--mixed`. The __ must be one of the following:\n+\tSet the current branch head (`HEAD`) to point at __.\n+\tDepending on __, also update the working directory and/or index\n+\tto match the contents of __.\n+\t__ defaults to `HEAD`.\n+\tBefore the operation, `ORIG_HEAD` is set to the tip of the current branch.\n++\n+The __ must be one of the following (default `--mixed`):\n +\n---\n-`--soft`::\n-\tDoes not touch the index file or the working tree at all (but\n-\tresets the head to __, just like all modes do). This leaves\n-\tall your changed files \"Changes to be committed\", as `git status`\n-\twould put it.\n \n+--\n `--mixed`::\n-\tResets the index but not the working tree (i.e., the changed files\n-\tare preserved but not marked for commit) and reports what has not\n-\tbeen updated. This is the default action.\n+\tLeaves your working directory unchanged.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n +\n If `-N` is specified, removed paths are marked as intent-to-add (see\n linkgit:git-add[1]).\n \n+`--soft`::\n+\tLeaves your working directory unchanged. The index is left unchanged,\n+\tso everything in your current commit will be staged.\n+\tFor example, if you have no staged changes, you can use\n+\t`git reset --soft HEAD~5; git commit`\n+\tto combine the last 5 commits into 1 commit.\n+\n `--hard`::\n-\tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since __ are discarded. Any untracked files or\n-\tdirectories in the way of writing any tracked files are simply deleted.\n+\tOverwrites all files and directories with the version from __,\n+\tand may overwrite untracked files.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n \n `--merge`::\n+\tMainly exists for backwards compatibility: `git merge --abort` is the\n+\tusual way to abort a merge. See linkgit:git-merge[1] for the differences.\n \tResets the index and updates the files in the working tree that are\n \tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n \tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n-+\n-In other words, `--merge` does something like a `git read-tree -u -m `,\n-but carries forward unmerged index entries.\n \n `--keep`::\n \tResets index entries and updates files in the working tree that are\n-- \ngitgitgadget\n\n"},{"id":"529096","messageId":"0be166483f547de866744917e6cb19eed13a8088.1760731558.git.gitgitgadget@gmail.com","threadId":"64347","inReplyTo":"pull.1991.git.1760731558.gitgitgadget@gmail.com","subject":"[PATCH 4/4] doc: git-reset: clarify `git reset `","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-10-17T20:05:58Z","receivedAt":"2025-10-17T20:06:06Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- Continued confusion about the terms \"tree-ish\" and \"pathspec\"\n- The word \"hunks\" is confusing folks, use \"changes\" instead.\n- On the part about `git restore`, there were a few comments to the\n effect of \"wait, this doesn't actually update any files? What? Why?\"\n Be more direct that `git reset` does not update files: there's no\n obvious reason to suggest that folks use `git reset` followed by `git\n restore`, instead suggest just using `git restore`.\n\nContinue avoiding the use of the word \"reset\" to\ndescribe what \"git reset\" does.\n\nSigned-off-by: Julia Evans \n---\n Documentation/git-reset.adoc | 27 +++++++++++----------------\n 1 file changed, 11 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex fa4bb2b551..52d380a756 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -79,29 +79,24 @@ linkgit:git-add[1]).\n \n `git reset [-q] [] [--] ...`::\n `git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n+\tFor all specified files or directories, set the staged version to\n+\tthe version from the given commit or tree (which defaults to `HEAD`).\n +\n This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n+`: it unstages all changes to the specified file(s) or\n+directories. This is equivalent to `git restore --staged ...`.\n +\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n+`git reset` only modifies the index: use linkgit:git-restore[1] instead\n+if you'd like to also update the file in your working directory.\n \n `git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n+\tInteractively select changes from the difference between the index\n+\tand the specified commit or tree (which defaults to `HEAD`).\n+\tThe chosen changes are unstaged.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+you can use it to selectively unstage changes. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to use the `--patch` option.\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n-- \ngitgitgadget\n"},{"id":"529104","messageId":"xmqqikgdxj93.fsf@gitster.g","threadId":"64347","inReplyTo":"c7e1c090475f76d94363018681c34f3955abe87e.1760731558.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/4] doc: git-reset: reorder the forms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-17T22:20:56Z","receivedAt":"2025-10-17T22:20:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n> index 3b9ba9aee9..9843682e81 100644\n> --- a/Documentation/git-reset.adoc\n> +++ b/Documentation/git-reset.adoc\n> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n> SYNOPSIS\n> --------\n> [synopsis]\n> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n> git reset [-q] [] [--] ...\n> git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n> git reset (--patch | -p) [] [--] [...]\n> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n> \n> DESCRIPTION\n> -----------\n> -In the first three forms, copy entries from __ to the index.\n> -In the last form, set the current branch head (`HEAD`) to __,\n> +In the first form, set the current branch head (`HEAD`) to __,\n> optionally modifying index and working tree to match.\n> The __/__ defaults to `HEAD` in all forms.\n\nIn the original, the \"defaults to HEAD in all forms\" did make sense,\nbut as the new text does not mention there are three other forms\nlike the original did, that sentence was made harder to fathom.\nI can accept that you do not want to get ahead of yourself to\nexplain \"copy from \" before you are ready to talk more\nabout these other forms, but we'd at least need to acknowledge that\nwhat we want to refer to when we say \"all forms\" here. Perhaps\n\n Among the four forms, the first form sets the current branch\n head to .... In all forms, the tree-ish/commit defaults to\n HEAD.\n\nis easier to read?\n\n> +In the last three forms, copy entries from __ to the index.\n\nOr \"The other three forms copy entries ...\"?\n\nOther than that, looks good to me.\n"},{"id":"529106","messageId":"xmqqecr1xiqc.fsf@gitster.g","threadId":"64347","inReplyTo":"6b5459b7ab478de33d17f9518906396f8a01e0d6.1760731558.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] doc: git-reset: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-17T22:32:11Z","receivedAt":"2025-10-17T22:32:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> From: Julia Evans \n>\n> From user feedback, there were several points of confusion:\n>\n> - What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n> (\"I have no clue what the index is\", \"I've been using git for 20 years\n> and still don't know what a tree-ish is\"). Avoid using these terms\n> where it makes sense.\n> - What \"optionally modifying index and working tree to match\" means\n> (\"to match what?\" \"optionally based on what?\")\n> Remove this from the intro, we can say it later when giving more\n> details.\n> - One user suggested that \"The / defaults to HEAD\n> in all forms.\" should be repeated later on, since it's easy to miss.\n> Instead say that HEAD is the default in each case later.\n>\n> Another issue is that `git reset` consistently describes the action\n> it does as \"Reset ...\", commands should not use their name to describe\n> themselves, and that the word \"mode\" is used to mean several different\n> things on this page.\n>\n> Address these by being more clear about two use cases for `git reset`\n> (\"to undo operations\" and \"to update staged files\"), and explaining what\n> the conditions are for each case instead of forcing the user to figure\n> out the pattern is in first form vs the other 3 forms.\n>\n> Signed-off-by: Julia Evans \n> ---\n> Documentation/git-reset.adoc | 13 ++++++++-----\n> 1 file changed, 8 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n> index 9843682e81..876187dc83 100644\n> --- a/Documentation/git-reset.adoc\n> +++ b/Documentation/git-reset.adoc\n> @@ -3,7 +3,7 @@ git-reset(1)\n> \n> NAME\n> ----\n> -git-reset - Reset current HEAD to the specified state\n> +git-reset - Set HEAD to point at the specified commit\n\nThe command has dual-purpose, and it is a bit disturbing that the\nother one is not even mentioned in the original or in the updated\ntext. \"The other three forms\" is about resetting the index without\nmoving HEAD at all. Would this work better, I wonder?\n\n Reset HEAD or index back to a known state\n\n> +`git reset [] ` changes which commit HEAD points to.\n> +This makes it possible to undo various Git operations, for example\n> +commit, merge, rebase, and pull.\n\nGood. These are prime examples of when resetting to a known state\nis useful.\n\n> +However, when you specify files or directories or pass `--patch`,\n> +`git reset` will instead update the staged version of the specified\n> +files without updating HEAD.\n\nI see no however here.\n\nOther forms are not about flipping HEAD to any state we used to have\nbefore. Instead, they are about populating index entries from the\nstate taken from an arbitrary tree-ish.\n\nYou can view them as enhanced variants of \"git reset --mixed HEAD\"\n(read it as \"unstage all changes\"). They are enhanced in the sense\nthat unlike \"git reset --mixed HEAD\", the treeish the index entries\nare taken from does not have to be HEAD, and also in the sense that\nunlike \"git reset --mixed HEAD\", you can limit the index entries to\nbe affected to a subset of paths. I am not sure it would make it\neasier to understand to explain them in terms of \"reset --mixed HEAD\"\nbut I am reasonably sure that it would appear confusing until a\nreader realizes that the command has two very disinct mode, one that\nis primarily about HEAD, the other that is primarily about index.\n\n> `git reset [] []`::\n> \tThis form resets the current branch head to __ and\n"},{"id":"529107","messageId":"xmqqa51pxg9p.fsf@gitster.g","threadId":"64347","inReplyTo":"0be166483f547de866744917e6cb19eed13a8088.1760731558.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc: git-reset: clarify `git reset `","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-17T23:25:22Z","receivedAt":"2025-10-17T23:25:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> +`git reset` only modifies the index: use linkgit:git-restore[1] instead\n> +if you'd like to also update the file in your working directory.\n\nI cannot judge if it is clear enough with the above sentence that we\nare only talking about \"the other forms\", but if that is the case\nand it is clear we are not talking about the mode where the command\nrepoints HEAD to another commit, the above is a good piece of advice.\n\nIf not, perhaps\n\n When specified what paths to modify, `git reset` updates only\n the index (without updating the HEAD or working tree files). If\n you want to update the files as well as the index entries, use\n git-restore.\n\nmay be a way to clarify the distinction between two modes.\n\n> `git reset (--patch | -p) [] [--] [...]`::\n> -\tInteractively select hunks in the difference between the index\n> -\tand __ (defaults to `HEAD`). The chosen hunks are applied\n> -\tin reverse to the index.\n> +\tInteractively select changes from the difference between the index\n> +\tand the specified commit or tree (which defaults to `HEAD`).\n> +\tThe chosen changes are unstaged.\n> +\n> This means that `git reset -p` is the opposite of `git add -p`, i.e.\n> -you can use it to selectively reset hunks. See the \"Interactive Mode\"\n> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n> +you can use it to selectively unstage changes. See the \"Interactive Mode\"\n> +section of linkgit:git-add[1] to learn how to use the `--patch` option.\n\nI do not see a good reason why we avoid saying the noun \"patch\",\nespecially when we see it in the option. If we were allowed to say\n\"patch\" here, \"changes from the difference between ...\" can be\nrephrased to \"parts of the patch that makes the index match the\nspecified commit\", which may be simpler.\n\nAlso \"unstaged\" is only true when is \"HEAD\". If you are\ngrabbing the contents recorded in a different commit and shoving\nthem into the index, that is not \"unstaging\" at all. Rather, if you\nare planning to make a commit out of the index after doing so, that\nis rather \"staging\" a change! While the verb \"to (un)stage\" may\nhave been a useful tool to explain the act of updating index entries\nto describe its effect relative to what is in HEAD, in this\nparticular case, it is probably more confusing than illuninating to\nuse it.\n\n\n"},{"id":"529112","messageId":"xmqqy0p8x12c.fsf@gitster.g","threadId":"64347","inReplyTo":"597ea0f5ce24967974358e18603265b14322ba54.1760731558.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-18T04:53:47Z","receivedAt":"2025-10-18T04:53:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" writes:\n\n> +`--soft`::\n> +\tLeaves your working directory unchanged. The index is left unchanged,\n\nWhy not \"leave your working tree files and the index unchanged\"?\n\n> +\tso everything in your current commit will be staged.\n\nHmph, if a reader still has the \"stage the changes\" mental model,\nthen this would be true only when you are resetting to HEAD~1 (this\nis one of the reasons why I am hesitant to overuse the verb\n\"stage\"). If you are going to HEAD~5, such a reader would say that\nthe changes made by the past 5 commits are staged, not just the\ncommit you are on before resetting.\n\n> +\tFor example, if you have no staged changes, you can use\n> +\t`git reset --soft HEAD~5; git commit`\n> +\tto combine the last 5 commits into 1 commit.\n\nAnother thing that may be worth mentioning is that you can do this\neven with local changes in the working tree, because you do not give\n\"-a\" to the final \"git commit\".\n\n> `--hard`::\n> -\tResets the index and working tree. Any changes to tracked files in the\n> -\tworking tree since __ are discarded. Any untracked files or\n> -\tdirectories in the way of writing any tracked files are simply deleted.\n> +\tOverwrites all files and directories with the version from __,\n> +\tand may overwrite untracked files.\n> +\tUpdates the index to match the new HEAD, so nothing will be staged.\n\nOne thing that may be worth saying is that the paths in the working\ntree that are tracked in the index that are not in will\ndisappear.\n\n> `--merge`::\n> +\tMainly exists for backwards compatibility: `git merge --abort` is the\n> +\tusual way to abort a merge. See linkgit:git-merge[1] for the differences.\n\nThere are operations that are not \"git merge\" that can leave the\nindex in an unmerged state, and you do not want to use \"git merge\n--abort\" to get out of such a state, I would imagine. So I have a\nfeeling that we are better off without these two lines.\n\n> \tResets the index and updates the files in the working tree that are\n> \tdifferent between __ and `HEAD`, but keeps those which are\n> \tdifferent between the index and working tree (i.e. which have changes\n> \twhich have not been added).\n> \tIf a file that is different between __ and the index has\n> \tunstaged changes, reset is aborted.\n> -+\n> -In other words, `--merge` does something like a `git read-tree -u -m `,\n> -but carries forward unmerged index entries.\n\nI do not mind losing this. Unlike the time back when these two\nlines were written, nobody knows (and more importantly, nobody has\nto know) what \"read-tree -u -m\" does, these days.\n\n> `--keep`::\n> \tResets index entries and updates files in the working tree that are\n\nThanks.\n"},{"id":"529125","messageId":"9EB375A8-CDD0-4717-B1DF-32DC3078A50A@gmail.com","threadId":"64347","inReplyTo":"xmqqa51pxg9p.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc: git-reset: clarify `git reset `","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-18T14:06:21Z","receivedAt":"2025-10-18T14:06:34Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 17 oct. 2025 à 19:25, Junio C Hamano a écrit :\n> \n> \"Julia Evans via GitGitGadget\" writes:\n> \n>> `git reset (--patch | -p) [] [--] [...]`::\n>> - Interactively select hunks in the difference between the index\n>> - and __ (defaults to `HEAD`). The chosen hunks are applied\n>> - in reverse to the index.\n>> + Interactively select changes from the difference between the index\n>> + and the specified commit or tree (which defaults to `HEAD`).\n>> + The chosen changes are unstaged.\n>> +\n>> This means that `git reset -p` is the opposite of `git add -p`, i.e.\n>> -you can use it to selectively reset hunks. See the \"Interactive Mode\"\n>> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n>> +you can use it to selectively unstage changes. See the \"Interactive Mode\"\n>> +section of linkgit:git-add[1] to learn how to use the `--patch` option.\n> \n> I do not see a good reason why we avoid saying the noun \"patch\",\n> especially when we see it in the option. If we were allowed to say\n> \"patch\" here, \"changes from the difference between ...\" can be\n> rephrased to \"parts of the patch that makes the index match the\n> specified commit\", which may be simpler.\n\nI think the issue was the word « hunk », not « patch »."},{"id":"529131","messageId":"xmqqy0p8uqu5.fsf@gitster.g","threadId":"64347","inReplyTo":"9EB375A8-CDD0-4717-B1DF-32DC3078A50A@gmail.com","subject":"Re: [PATCH 4/4] doc: git-reset: clarify `git reset `","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-18T16:17:38Z","receivedAt":"2025-10-18T16:17:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Knoble writes:\n\n>> Le 17 oct. 2025 à 19:25, Junio C Hamano a écrit :\n>> \n>> \"Julia Evans via GitGitGadget\" writes:\n>> \n>>> `git reset (--patch | -p) [] [--] [...]`::\n>>> - Interactively select hunks in the difference between the index\n>>> - and __ (defaults to `HEAD`). The chosen hunks are applied\n>>> - in reverse to the index.\n>>> + Interactively select changes from the difference between the index\n>>> + and the specified commit or tree (which defaults to `HEAD`).\n>>> + The chosen changes are unstaged.\n>>> +\n>>> This means that `git reset -p` is the opposite of `git add -p`, i.e.\n>>> -you can use it to selectively reset hunks. See the \"Interactive Mode\"\n>>> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n>>> +you can use it to selectively unstage changes. See the \"Interactive Mode\"\n>>> +section of linkgit:git-add[1] to learn how to use the `--patch` option.\n>> \n>> I do not see a good reason why we avoid saying the noun \"patch\",\n>> especially when we see it in the option. If we were allowed to say\n>> \"patch\" here, \"changes from the difference between ...\" can be\n>> rephrased to \"parts of the patch that makes the index match the\n>> specified commit\", which may be simpler.\n>\n> I think the issue was the word « hunk », not « patch ».\n\nI know. That is exactly where my question comes from.\n"},{"id":"529199","messageId":"8099e7ef-2673-407e-8cca-e6b566b99549@app.fastmail.com","threadId":"64347","inReplyTo":"xmqqikgdxj93.fsf@gitster.g","subject":"Re: [PATCH 1/4] doc: git-reset: reorder the forms","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-20T19:03:39Z","receivedAt":"2025-10-20T19:04:11Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Oct 17, 2025, at 6:20 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n>\n>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n>> index 3b9ba9aee9..9843682e81 100644\n>> --- a/Documentation/git-reset.adoc\n>> +++ b/Documentation/git-reset.adoc\n>> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n>> SYNOPSIS\n>> --------\n>> [synopsis]\n>> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n>> git reset [-q] [] [--] ...\n>> git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n>> git reset (--patch | -p) [] [--] [...]\n>> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n>> \n>> DESCRIPTION\n>> -----------\n>> -In the first three forms, copy entries from __ to the index.\n>> -In the last form, set the current branch head (`HEAD`) to __,\n>> +In the first form, set the current branch head (`HEAD`) to __,\n>> optionally modifying index and working tree to match.\n>> The __/__ defaults to `HEAD` in all forms.\n>\n> In the original, the \"defaults to HEAD in all forms\" did make sense,\n> but as the new text does not mention there are three other forms\n> like the original did, that sentence was made harder to fathom.\n\nThat's true. I didn't pay very careful attention to the text here\nbecause I completely rewrote it in a later patch anyway.\nI'll make it say something that makes more sense.\n\n> I can accept that you do not want to get ahead of yourself to\n> explain \"copy from \" before you are ready to talk more\n> about these other forms, but we'd at least need to acknowledge that\n> what we want to refer to when we say \"all forms\" here. Perhaps\n>\n> Among the four forms, the first form sets the current branch\n> head to .... In all forms, the tree-ish/commit defaults to\n> HEAD.\n>\n> is easier to read?\n>\n>> +In the last three forms, copy entries from __ to the index.\n>\n> Or \"The other three forms copy entries ...\"?\n>\n> Other than that, looks good to me.\n"},{"id":"529200","messageId":"4871df7e-4ab4-45ea-83bd-9a49e4d60561@app.fastmail.com","threadId":"64347","inReplyTo":"xmqqecr1xiqc.fsf@gitster.g","subject":"Re: [PATCH 2/4] doc: git-reset: clarify intro","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-20T19:29:00Z","receivedAt":"2025-10-20T19:29:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Fri, Oct 17, 2025, at 6:32 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n>\n>> From: Julia Evans \n>>\n>> From user feedback, there were several points of confusion:\n>>\n>> - What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n>> (\"I have no clue what the index is\", \"I've been using git for 20 years\n>> and still don't know what a tree-ish is\"). Avoid using these terms\n>> where it makes sense.\n>> - What \"optionally modifying index and working tree to match\" means\n>> (\"to match what?\" \"optionally based on what?\")\n>> Remove this from the intro, we can say it later when giving more\n>> details.\n>> - One user suggested that \"The / defaults to HEAD\n>> in all forms.\" should be repeated later on, since it's easy to miss.\n>> Instead say that HEAD is the default in each case later.\n>>\n>> Another issue is that `git reset` consistently describes the action\n>> it does as \"Reset ...\", commands should not use their name to describe\n>> themselves, and that the word \"mode\" is used to mean several different\n>> things on this page.\n>>\n>> Address these by being more clear about two use cases for `git reset`\n>> (\"to undo operations\" and \"to update staged files\"), and explaining what\n>> the conditions are for each case instead of forcing the user to figure\n>> out the pattern is in first form vs the other 3 forms.\n>>\n>> Signed-off-by: Julia Evans \n>> ---\n>> Documentation/git-reset.adoc | 13 ++++++++-----\n>> 1 file changed, 8 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n>> index 9843682e81..876187dc83 100644\n>> --- a/Documentation/git-reset.adoc\n>> +++ b/Documentation/git-reset.adoc\n>> @@ -3,7 +3,7 @@ git-reset(1)\n>> \n>> NAME\n>> ----\n>> -git-reset - Reset current HEAD to the specified state\n>> +git-reset - Set HEAD to point at the specified commit\n>\n> The command has dual-purpose, and it is a bit disturbing that the\n> other one is not even mentioned in the original or in the updated\n> text. \"The other three forms\" is about resetting the index without\n> moving HEAD at all. Would this work better, I wonder?\n>\n> Reset HEAD or index back to a known state\n\nThat's true, though I think we should avoid using \"Reset\"\nto explain what `git reset` does. Perhaps\n\n Set HEAD or the index to a previous state\n\n>> +`git reset [] ` changes which commit HEAD points to.\n>> +This makes it possible to undo various Git operations, for example\n>> +commit, merge, rebase, and pull.\n>\n> Good. These are prime examples of when resetting to a known state\n> is useful.\n>\n>> +However, when you specify files or directories or pass `--patch`,\n>> +`git reset` will instead update the staged version of the specified\n>> +files without updating HEAD.\n>\n> I see no however here.\n>\n> Other forms are not about flipping HEAD to any state we used to have\n> before. Instead, they are about populating index entries from the\n> state taken from an arbitrary tree-ish.\n>\n> You can view them as enhanced variants of \"git reset --mixed HEAD\"\n> (read it as \"unstage all changes\"). They are enhanced in the sense\n> that unlike \"git reset --mixed HEAD\", the treeish the index entries\n> are taken from does not have to be HEAD, and also in the sense that\n> unlike \"git reset --mixed HEAD\", you can limit the index entries to\n> be affected to a subset of paths. I am not sure it would make it\n> easier to understand to explain them in terms of \"reset --mixed HEAD\"\n> but I am reasonably sure that it would appear confusing until a\n> reader realizes that the command has two very disinct mode, one that\n> is primarily about HEAD, the other that is primarily about index.\n>\n>> `git reset [] []`::\n>> \tThis form resets the current branch head to __ and\n\nI agree that \"git reset has two very distinct modes' is important.\nHere's an idea for how to communicate that.\nIt doesn't fully capture all of the nuances of `git reset`'s command\nline syntax, but maybe that's not the job of the intro sentence anyway.\n\nI don't love the use of \"things\" in \"two things\" but it would be weird to\nsay \"modes\" because we already use \"mode\" to mean something else,\nand I haven't thought of something better yet.\n\n`git reset` does two things:\n\n1. `git reset [] ` changes which commit HEAD points to.\n This makes it possible to undo various Git operations, for example\n commit, merge, rebase, and pull.\n2. When you specify files or directories or pass `--patch`, it updates\n the staged version of the specified files.\n"},{"id":"529201","messageId":"xmqqjz0pz6l4.fsf@gitster.g","threadId":"64347","inReplyTo":"4871df7e-4ab4-45ea-83bd-9a49e4d60561@app.fastmail.com","subject":"Re: [PATCH 2/4] doc: git-reset: clarify intro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-20T20:00:39Z","receivedAt":"2025-10-20T20:00:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n>> Reset HEAD or index back to a known state\n>\n> That's true, though I think we should avoid using \"Reset\"\n> to explain what `git reset` does. Perhaps\n>\n> Set HEAD or the index to a previous state\n\nOK, though the state is not necessarily \"previous\".\n\n> I agree that \"git reset has two very distinct modes' is important.\n> Here's an idea for how to communicate that.\n> It doesn't fully capture all of the nuances of `git reset`'s command\n> line syntax, but maybe that's not the job of the intro sentence anyway.\n>\n> I don't love the use of \"things\" in \"two things\" but it would be weird to\n> say \"modes\" because we already use \"mode\" to mean something else,\n> and I haven't thought of something better yet.\n>\n> `git reset` does two things:\n\nI do not mind \"things\", as long as it is not mislead readers into\nthinking that it may do two things at the same time. \"modes\" avoids\nthat problem, as \"you use it one way, and it does one thing, and you\nuse it another way, and it does a very different thing\" is the\nnatural implication of that word.\n\n\"The command can be used in two ways\"? \"can be used for two\ndifferent purposes?\" I dunno.\n"},{"id":"529202","messageId":"a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com","threadId":"64347","inReplyTo":"xmqqy0p8x12c.fsf@gitster.g","subject":"Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-10-20T20:23:44Z","receivedAt":"2025-10-20T20:24:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" writes:\n>\n>> +`--soft`::\n>> +\tLeaves your working directory unchanged. The index is left unchanged,\n>\n> Why not \"leave your working tree files and the index unchanged\"?\n\nThe reason I say \"working directory\" instead of \"working tree\" is that\nI've seen a few comments from users saying that they don't know\nwhat \"working tree\" means. I'm still not sure what the reason for\ncalling it a \"working tree\" is.\n\nThe reason for keeping them separate sentences is just for symmetry with\nthe other commands, and also because (like I mentioned in the commit\nmessage) \"leaving X and Y unchanged\" makes it sound like leaving X and\nY unchanged is a \"neutral operation\", while actually leaving the index\nunchanged while updating HEAD is actually a fairly weird thing to do.\n\n>> +\tso everything in your current commit will be staged.\n>\n> Hmph, if a reader still has the \"stage the changes\" mental model,\n> then this would be true only when you are resetting to HEAD~1 (this\n> is one of the reasons why I am hesitant to overuse the verb\n> \"stage\"). If you are going to HEAD~5, such a reader would say that\n> the changes made by the past 5 commits are staged, not just the\n> commit you are on before resetting.\n\nThat's fair. I'll try to think about whether there's a better way to say\nthis.\n\nPreviously it said \"This leaves all your changed files\n\"Changes to be committed\", as git status would put it.\", which has the\nsame issue (\"changed files\" since when exactly?).\nMaybe I can fix this by being more explicit about which changes\nexactly will show up as \"staged\" in `git status`.\n\n>> +\tFor example, if you have no staged changes, you can use\n>> +\t`git reset --soft HEAD~5; git commit`\n>> +\tto combine the last 5 commits into 1 commit.\n>\n> Another thing that may be worth mentioning is that you can do this\n> even with local changes in the working tree, because you do not give\n> \"-a\" to the final \"git commit\".\n\nMaybe! I'm not sure if we want to encourage doing complex Git operations\nwith unstaged changes though. I feel like it often leads to suffering\nand I think people who want to do that can already infer that it's\npossible.\n\n>> `--hard`::\n>> -\tResets the index and working tree. Any changes to tracked files in the\n>> -\tworking tree since __ are discarded. Any untracked files or\n>> -\tdirectories in the way of writing any tracked files are simply deleted.\n>> +\tOverwrites all files and directories with the version from __,\n>> +\tand may overwrite untracked files.\n>> +\tUpdates the index to match the new HEAD, so nothing will be staged.\n>\n> One thing that may be worth saying is that the paths in the working\n> tree that are tracked in the index that are not in will\n> disappear.\n\nInteresting, I don't think I knew that. Would this be a more accurate\ndescription of what `git reset --hard` does, conceptually?\nI want to make sure I understand how it works.\n\n1. List every file that's either in the target commit or in the index\n2. For each file, make it match the target commit\n (overwriting untracked files if necessary)\n\n>> `--merge`::\n>> +\tMainly exists for backwards compatibility: `git merge --abort` is the\n>> +\tusual way to abort a merge. See linkgit:git-merge[1] for the differences.\n>\n> There are operations that are not \"git merge\" that can leave the\n> index in an unmerged state, and you do not want to use \"git merge\n> --abort\" to get out of such a state, I would imagine. So I have a\n> feeling that we are better off without these two lines.\n\nDo you mean `git reset` and `git cherry-pick`, or are there other operations\nthat can leave the operation in an unmerged state?\nMy mental model is that if there's a merge conflict, the best way to deal with it\nis to use the appropriate `--abort` command (depending on how you got there),\nbecause the command-specific `--abort` will know how to do things like\nrestore autostashed changes. But I agree that just saying \"use `git merge --abort`\nis not a complete description.\n\n>> \tResets the index and updates the files in the working tree that are\n>> \tdifferent between __ and `HEAD`, but keeps those which are\n>> \tdifferent between the index and working tree (i.e. which have changes\n>> \twhich have not been added).\n>> \tIf a file that is different between __ and the index has\n>> \tunstaged changes, reset is aborted.\n>> -+\n>> -In other words, `--merge` does something like a `git read-tree -u -m `,\n>> -but carries forward unmerged index entries.\n>\n> I do not mind losing this. Unlike the time back when these two\n> lines were written, nobody knows (and more importantly, nobody has\n> to know) what \"read-tree -u -m\" does, these days.\n\nThanks, it's useful for me to know more about the context at the time\nthis was written.\n"},{"id":"529205","messageId":"CALnO6CDyCvSSRBTAzS354M5QKhqcOHOHokT1KwEqY7+58A-yfQ@mail.gmail.com","threadId":"64347","inReplyTo":"xmqqjz0pz6l4.fsf@gitster.g","subject":"Re: [PATCH 2/4] doc: git-reset: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-20T20:30:07Z","receivedAt":"2025-10-20T20:30:20Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Oct 20, 2025 at 4:02 PM Junio C Hamano wrote:\n>\n> \"Julia Evans\" writes:\n> > I agree that \"git reset has two very distinct modes' is important.\n> > Here's an idea for how to communicate that.\n> > It doesn't fully capture all of the nuances of `git reset`'s command\n> > line syntax, but maybe that's not the job of the intro sentence anyway.\n> >\n> > I don't love the use of \"things\" in \"two things\" but it would be weird to\n> > say \"modes\" because we already use \"mode\" to mean something else,\n> > and I haven't thought of something better yet.\n> >\n> > `git reset` does two things:\n>\n> I do not mind \"things\", as long as it is not mislead readers into\n> thinking that it may do two things at the same time. \"modes\" avoids\n> that problem, as \"you use it one way, and it does one thing, and you\n> use it another way, and it does a very different thing\" is the\n> natural implication of that word.\n>\n> \"The command can be used in two ways\"? \"can be used for two\n> different purposes?\" I dunno.\n\nSome options:\n\n `git reset` does one of two different things\n\n `git reset` can be used to accomplish either of the following:\n\n-- \nD. Ben Knoble\n"},{"id":"529206","messageId":"CALnO6CA=_xQWVWkUONPA_p6fiCjeMkq8pw0SmgXzo0sUPMHNFA@mail.gmail.com","threadId":"64347","inReplyTo":"a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com","subject":"Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-10-20T20:33:36Z","receivedAt":"2025-10-20T20:33:49Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Oct 20, 2025 at 4:28 PM Julia Evans wrote:\n>\n> On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:\n> > \"Julia Evans via GitGitGadget\" writes:\n> >\n> >> +`--soft`::\n> >> + Leaves your working directory unchanged. The index is left unchanged,\n> >\n> > Why not \"leave your working tree files and the index unchanged\"?\n>\n> The reason I say \"working directory\" instead of \"working tree\" is that\n> I've seen a few comments from users saying that they don't know\n> what \"working tree\" means. I'm still not sure what the reason for\n> calling it a \"working tree\" is.\n\nAt a guess: suppose I have a non-bare repository ~/code/git with\ncorresponding ~/code/git/.git directory, but PWD=~/code/git/t. Then my\nworking directory is \"…/t\" but my working tree includes all the stuff\nGit is tracking above me, too! (It also helps draw parallelism with\ngit-worktree, but that's a bit circular.)\n"},{"id":"529207","messageId":"xmqqcy6hz4jh.fsf@gitster.g","threadId":"64347","inReplyTo":"a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com","subject":"Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-10-20T20:44:50Z","receivedAt":"2025-10-20T20:44:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" writes:\n\n> On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:\n>> \"Julia Evans via GitGitGadget\" writes:\n>>\n>>> +`--soft`::\n>>> +\tLeaves your working directory unchanged. The index is left unchanged,\n>>\n>> Why not \"leave your working tree files and the index unchanged\"?\n>\n> The reason I say \"working directory\" instead of \"working tree\" is that\n> I've seen a few comments from users saying that they don't know\n> what \"working tree\" means. I'm still not sure what the reason for\n> calling it a \"working tree\" is.\n\n\"working tree\" refers to the directory that is the top level of a\ncheckout; I'd view (current) \"working directory\" can be anything\n$(pwd), that may be outside control of any git repository, and that\nis why I tend to avoid the latter when I want to be more precise\n(and \"worktree\" is another thing---used to refer to one particular\n\"working tree\" among other working trees attached to the same\nrepository).\n\nBut that distinction was not the part I wanted to comment on. The\nquestion was about two sentences talking about two things\nseparately. IOW\n\n\tLeave your working directory and the index unchanged.\n\nis what I would have expected, and I was wondering why they are\ntreated separately. After all, the index is part of your working\ntree state.\n\n> The reason for keeping them separate sentences is just for symmetry with\n> the other commands, and also because (like I mentioned in the commit\n> message) \"leaving X and Y unchanged\" makes it sound like leaving X and\n> Y unchanged is a \"neutral operation\", while actually leaving the index\n> unchanged while updating HEAD is actually a fairly weird thing to do.\n\nSorry, but I do not understand this comment.\n\nThe index and the HEAD are two different things, and it is natural\nthat they can move independently. After all we update the former\nwithout updating the latter all the time (it is called \"git add\").\n\nBesides, the two things the --soft does not touch are the files in\nthe working tree and the index. The index has what you want to make\nthe next commit out of, and the working tree has the state that may\ncome after that state in the index. Keeping both of them intact\nwhen moving HEAD around is one natural thing to do when you want to\nsquash the previous N commits after \"git add \" by doing \"git\nreset --soft HEAD~N && git commit\". Contrasting to that, \"--mixed\"\nwould leave the files in the working tree intact, while matching the\nindex to the HEAD you are moving to, essentially undoing your \"git\nadd\"s before you decided to reset. That's another natural thing to\ndo when you decide to keep the clean slate and rebuild your index from\nscratch to prepare for a commit that comes on top of the commit you\nare moving to.\n\nSo, no, I do not understand the above comment.\n\n> Do you mean `git reset` and `git cherry-pick`, or are there other operations\n> that can leave the operation in an unmerged state?\n\nThere are many commands that leaves the index unmerged, like \"am\n-3\", \"rebase\", \"switch -m\", \"stash pop\", etc.\n\n"},{"id":"531631","messageId":"b09c955f-06d1-4dcd-949d-cc723a9604ac@app.fastmail.com","threadId":"64347","inReplyTo":"4871df7e-4ab4-45ea-83bd-9a49e4d60561@app.fastmail.com","subject":"Re: [PATCH 2/4] doc: git-reset: clarify intro","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2025-12-03T18:15:01Z","receivedAt":"2025-12-03T18:15:22Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I was hoping to be able to finish this, but I don't have funding to\nwork on the Git docs (I imagine like everyone else who works on them! :) )\nand the time I budgeted to do this work has run out for now.\n\nIt's been really interesting to get to dig into the Git documentation\nand I really appreciate all of the reviews & encouragement along the way.\n\nall the best,\nJulia\n\nOn Mon, Oct 20, 2025, at 3:29 PM, Julia Evans wrote:\n> On Fri, Oct 17, 2025, at 6:32 PM, Junio C Hamano wrote:\n>> \"Julia Evans via GitGitGadget\" writes:\n>>\n>>> From: Julia Evans \n>>>\n>>> From user feedback, there were several points of confusion:\n>>>\n>>> - What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n>>> (\"I have no clue what the index is\", \"I've been using git for 20 years\n>>> and still don't know what a tree-ish is\"). Avoid using these terms\n>>> where it makes sense.\n>>> - What \"optionally modifying index and working tree to match\" means\n>>> (\"to match what?\" \"optionally based on what?\")\n>>> Remove this from the intro, we can say it later when giving more\n>>> details.\n>>> - One user suggested that \"The / defaults to HEAD\n>>> in all forms.\" should be repeated later on, since it's easy to miss.\n>>> Instead say that HEAD is the default in each case later.\n>>>\n>>> Another issue is that `git reset` consistently describes the action\n>>> it does as \"Reset ...\", commands should not use their name to describe\n>>> themselves, and that the word \"mode\" is used to mean several different\n>>> things on this page.\n>>>\n>>> Address these by being more clear about two use cases for `git reset`\n>>> (\"to undo operations\" and \"to update staged files\"), and explaining what\n>>> the conditions are for each case instead of forcing the user to figure\n>>> out the pattern is in first form vs the other 3 forms.\n>>>\n>>> Signed-off-by: Julia Evans \n>>> ---\n>>> Documentation/git-reset.adoc | 13 ++++++++-----\n>>> 1 file changed, 8 insertions(+), 5 deletions(-)\n>>>\n>>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n>>> index 9843682e81..876187dc83 100644\n>>> --- a/Documentation/git-reset.adoc\n>>> +++ b/Documentation/git-reset.adoc\n>>> @@ -3,7 +3,7 @@ git-reset(1)\n>>> \n>>> NAME\n>>> ----\n>>> -git-reset - Reset current HEAD to the specified state\n>>> +git-reset - Set HEAD to point at the specified commit\n>>\n>> The command has dual-purpose, and it is a bit disturbing that the\n>> other one is not even mentioned in the original or in the updated\n>> text. \"The other three forms\" is about resetting the index without\n>> moving HEAD at all. Would this work better, I wonder?\n>>\n>> Reset HEAD or index back to a known state\n>\n> That's true, though I think we should avoid using \"Reset\"\n> to explain what `git reset` does. Perhaps\n>\n> Set HEAD or the index to a previous state\n>\n>>> +`git reset [] ` changes which commit HEAD points to.\n>>> +This makes it possible to undo various Git operations, for example\n>>> +commit, merge, rebase, and pull.\n>>\n>> Good. These are prime examples of when resetting to a known state\n>> is useful.\n>>\n>>> +However, when you specify files or directories or pass `--patch`,\n>>> +`git reset` will instead update the staged version of the specified\n>>> +files without updating HEAD.\n>>\n>> I see no however here.\n>>\n>> Other forms are not about flipping HEAD to any state we used to have\n>> before. Instead, they are about populating index entries from the\n>> state taken from an arbitrary tree-ish.\n>>\n>> You can view them as enhanced variants of \"git reset --mixed HEAD\"\n>> (read it as \"unstage all changes\"). They are enhanced in the sense\n>> that unlike \"git reset --mixed HEAD\", the treeish the index entries\n>> are taken from does not have to be HEAD, and also in the sense that\n>> unlike \"git reset --mixed HEAD\", you can limit the index entries to\n>> be affected to a subset of paths. I am not sure it would make it\n>> easier to understand to explain them in terms of \"reset --mixed HEAD\"\n>> but I am reasonably sure that it would appear confusing until a\n>> reader realizes that the command has two very disinct mode, one that\n>> is primarily about HEAD, the other that is primarily about index.\n>>\n>>> `git reset [] []`::\n>>> \tThis form resets the current branch head to __ and\n>\n> I agree that \"git reset has two very distinct modes' is important.\n> Here's an idea for how to communicate that.\n> It doesn't fully capture all of the nuances of `git reset`'s command\n> line syntax, but maybe that's not the job of the intro sentence anyway.\n>\n> I don't love the use of \"things\" in \"two things\" but it would be weird to\n> say \"modes\" because we already use \"mode\" to mean something else,\n> and I haven't thought of something better yet.\n>\n> `git reset` does two things:\n>\n> 1. `git reset [] ` changes which commit HEAD points to.\n> This makes it possible to undo various Git operations, for example\n> commit, merge, rebase, and pull.\n> 2. When you specify files or directories or pass `--patch`, it updates\n> the staged version of the specified files.\n"},{"id":"532507","messageId":"cover.1766103827.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"pull.1991.git.1760731558.gitgitgadget@gmail.com","subject":"[PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-12-19T00:23:52Z","receivedAt":"2025-12-19T00:24:16Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"This continues Julia Evans's excellent work updating the git-reset docs.\n\nChanges in v2:\n- Mostly address Junio's review while keeping to Julia's style (?),\n taking at a stab at a few gray areas.\n- I left alone the first patch, the commented-upon part of which is\n later rewritten anyway.\n\nv1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/\nPublished-as: https://github.com/benknoble/git/tree/bk/je/doc-reset\n\nJulia Evans (4):\n doc: git-reset: reorder the forms\n doc: git-reset: clarify intro\n doc: git-reset: clarify `git reset [mode]`\n doc: git-reset: clarify `git reset `\n\n Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------\n 1 file changed, 54 insertions(+), 51 deletions(-)\n\nDiff-intervalle contre v1 :\n1: 5074fbf4ea ! 1: a558c5a868 doc: git-reset: reorder the forms\n @@ Metadata\n ## Commit message ##\n doc: git-reset: reorder the forms\n \n - >From user feedback: three users commented that the `git reset [mode]`\n + From user feedback: three users commented that the `git reset [mode]`\n form is the one that they primarily use, and that they were suprised to\n see it listed last.\n (\"I've never used git reset in any mode other than --hard\").\n2: c7049edf39 ! 2: f90be8559f doc: git-reset: clarify intro\n @@ Metadata\n ## Commit message ##\n doc: git-reset: clarify intro\n \n - >From user feedback, there were several points of confusion:\n + From user feedback, there were several points of confusion:\n \n - What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n (\"I have no clue what the index is\", \"I've been using git for 20 years\n @@ Documentation/git-reset.adoc: git-reset(1)\n NAME\n ----\n -git-reset - Reset current HEAD to the specified state\n -+git-reset - Set HEAD to point at the specified commit\n ++git-reset - Set HEAD or the index to a known state\n \n SYNOPSIS\n --------\n @@ Documentation/git-reset.adoc: git reset (--patch | -p) [] [--] [_/__ defaults to `HEAD` in all forms.\n -In the last three forms, copy entries from __ to the index.\n -+`git reset [] ` changes which commit HEAD points to.\n -+This makes it possible to undo various Git operations, for example\n -+commit, merge, rebase, and pull.\n ++`git reset` does either of the following:\n +\n -+However, when you specify files or directories or pass `--patch`,\n -+`git reset` will instead update the staged version of the specified\n -+files without updating HEAD.\n ++1. `git reset [] ` changes which commit HEAD points to. This makes\n ++ it possible to undo various Git operations, for example commit, merge,\n ++ rebase, and pull.\n ++2. When you specify files or directories or pass `--patch`, `git reset` updates\n ++ the staged version of the specified files.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n3: 84aed17da6 ! 3: 89c87c14aa doc: git-reset: clarify `git reset [mode]`\n @@ Metadata\n ## Commit message ##\n doc: git-reset: clarify `git reset [mode]`\n \n - >From user feedback, there was some confusion about the differences\n + From user feedback, there was some confusion about the differences\n between the modes, including:\n \n 1. Sometimes it says \"index\" and sometimes \"index file\".\n Fix by replacing \"index file\" with \"index\".\n 2. Many comments about not being able to understand what `--merge` does.\n - Fix by mentioning `git merge --abort` since my best guess is that\n - most folks want to use that instead of `git reset --merge`.\n + Fix by mentioning obscure situations, since that seems to be what\n + it's for. Most folks will use `git --abort`.\n 3. Issues telling the difference between --soft and --mixed, as well as\n --keep. Leave --keep alone because I couldn't understand its use case,\n but change `--soft` / `--mixed` / `--hard` as follows:\n @@ Commit message\n Signed-off-by: Junio C Hamano \n \n ## Documentation/git-reset.adoc ##\n -@@ Documentation/git-reset.adoc: However, when you specify files or directories or pass `--patch`,\n - files without updating HEAD.\n +@@ Documentation/git-reset.adoc: DESCRIPTION\n + the staged version of the specified files.\n \n `git reset [] []`::\n -\tThis form resets the current branch head to __ and\n @@ Documentation/git-reset.adoc: However, when you specify files or directories or\n linkgit:git-add[1]).\n \n +`--soft`::\n -+\tLeaves your working directory unchanged. The index is left unchanged,\n -+\tso everything in your current commit will be staged.\n ++\tLeave your working tree files and the index unchanged.\n +\tFor example, if you have no staged changes, you can use\n +\t`git reset --soft HEAD~5; git commit`\n -+\tto combine the last 5 commits into 1 commit.\n ++\tto combine the last 5 commits into 1 commit. This works even with\n ++\tchanges in the working tree, which are left untouched, but such usage\n ++\tcan lead to confusion.\n +\n `--hard`::\n -\tResets the index and working tree. Any changes to tracked files in the\n -\tworking tree since __ are discarded. Any untracked files or\n -\tdirectories in the way of writing any tracked files are simply deleted.\n +\tOverwrites all files and directories with the version from __,\n -+\tand may overwrite untracked files.\n ++\tand may overwrite untracked files. Tracked files not in __ are\n ++\tremoved so that the working tree matches __.\n +\tUpdates the index to match the new HEAD, so nothing will be staged.\n \n `--merge`::\n -+\tMainly exists for backwards compatibility: `git merge --abort` is the\n -+\tusual way to abort a merge. See linkgit:git-merge[1] for the differences.\n ++\tMainly exists to reset unmerged index entries, like those left behind by\n ++\t`git am -3` or `git switch -m` in certain situations.\n \tResets the index and updates the files in the working tree that are\n \tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n4: 0b9583f872 ! 4: d6582dc53c doc: git-reset: clarify `git reset `\n @@ Metadata\n ## Commit message ##\n doc: git-reset: clarify `git reset `\n \n - >From user feedback:\n + From user feedback:\n \n - Continued confusion about the terms \"tree-ish\" and \"pathspec\"\n - The word \"hunks\" is confusing folks, use \"changes\" instead.\n @@ Documentation/git-reset.adoc: linkgit:git-add[1]).\n -and specifying a commit with `--source`, you\n -can copy the contents of a path out of a commit to the index and to the\n -working tree in one go.\n -+`git reset` only modifies the index: use linkgit:git-restore[1] instead\n -+if you'd like to also update the file in your working directory.\n ++In this mode, `git reset` updates only the index (without updating the HEAD or\n ++working tree files). If you want to update the files as well as the index\n ++entries, use linkgit:git-restore[1].\n \n `git reset (--patch | -p) [] [--] [...]`::\n -\tInteractively select hunks in the difference between the index\n @@ Documentation/git-reset.adoc: linkgit:git-add[1]).\n -\tin reverse to the index.\n +\tInteractively select changes from the difference between the index\n +\tand the specified commit or tree (which defaults to `HEAD`).\n -+\tThe chosen changes are unstaged.\n ++\tThe chosen changes are added to the index.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n -you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-- \n2.52.0.rc0.365.g9bf09b728d.dirty\n\n"},{"id":"532508","messageId":"a558c5a8684639a2e888866a650357f54f29f2a6.1766103827.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1766103827.git.ben.knoble+github@gmail.com","subject":"[PATCH v2 1/4] doc: git-reset: reorder the forms","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-12-19T00:23:53Z","receivedAt":"2025-12-19T00:24:30Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: three users commented that the `git reset [mode]`\nform is the one that they primarily use, and that they were suprised to\nsee it listed last.\n(\"I've never used git reset in any mode other than --hard\").\n\nMove it to be first, since the `git reset [mode]` form is what\n\"Reset current HEAD to the specified state\" at the beginning refers\nto, and because the `git reset [mode]` form is the only thing that\n`git reset` uniquely does, the others could also be done with\n`git restore`.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------\n 1 file changed, 29 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 3b9ba9aee9..9843682e81 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n SYNOPSIS\n --------\n [synopsis]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n git reset [-q] [] [--] ...\n git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n git reset (--patch | -p) [] [--] [...]\n-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from __ to the index.\n-In the last form, set the current branch head (`HEAD`) to __,\n+In the first form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n The __/__ defaults to `HEAD` in all forms.\n-\n-`git reset [-q] [] [--] ...`::\n-`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n-+\n-This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n-+\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n-\n-`git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n-+\n-This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+In the last three forms, copy entries from __ to the index.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n@@ -98,6 +72,32 @@ but carries forward unmerged index entries.\n \tthe submodules' `HEAD` to be detached at that commit.\n --\n \n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n+\tThese forms reset the index entries for all paths that match the\n+\t__ to their state at __. (It does not affect\n+\tthe working tree or the current branch.)\n++\n+This means that `git reset ` is the opposite of `git add\n+`. This command is equivalent to\n+`git restore [--source=] --staged ...`.\n++\n+After running `git reset ` to update the index entry, you can\n+use linkgit:git-restore[1] to check the contents out of the index to\n+the working tree. Alternatively, using linkgit:git-restore[1]\n+and specifying a commit with `--source`, you\n+can copy the contents of a path out of a commit to the index and to the\n+working tree in one go.\n+\n+`git reset (--patch | -p) [] [--] [...]`::\n+\tInteractively select hunks in the difference between the index\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n+\tin reverse to the index.\n++\n+This means that `git reset -p` is the opposite of `git add -p`, i.e.\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-- \n2.52.0.rc0.365.g9bf09b728d.dirty\n\n"},{"id":"532509","messageId":"f90be8559f7d1d8362077a6f888687ee8be063b4.1766103827.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1766103827.git.ben.knoble+github@gmail.com","subject":"[PATCH v2 2/4] doc: git-reset: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-12-19T00:23:54Z","receivedAt":"2025-12-19T00:24:35Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there were several points of confusion:\n\n- What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n (\"I have no clue what the index is\", \"I've been using git for 20 years\n and still don't know what a tree-ish is\"). Avoid using these terms\n where it makes sense.\n- What \"optionally modifying index and working tree to match\" means\n (\"to match what?\" \"optionally based on what?\")\n Remove this from the intro, we can say it later when giving more\n details.\n- One user suggested that \"The / defaults to HEAD\n in all forms.\" should be repeated later on, since it's easy to miss.\n Instead say that HEAD is the default in each case later.\n\nAnother issue is that `git reset` consistently describes the action\nit does as \"Reset ...\", commands should not use their name to describe\nthemselves, and that the word \"mode\" is used to mean several different\nthings on this page.\n\nAddress these by being more clear about two use cases for `git reset`\n(\"to undo operations\" and \"to update staged files\"), and explaining what\nthe conditions are for each case instead of forcing the user to figure\nout the pattern is in first form vs the other 3 forms.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 9843682e81..71e8f52430 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -3,7 +3,7 @@ git-reset(1)\n \n NAME\n ----\n-git-reset - Reset current HEAD to the specified state\n+git-reset - Set HEAD or the index to a known state\n \n SYNOPSIS\n --------\n@@ -15,10 +15,13 @@ git reset (--patch | -p) [] [--] [...]\n \n DESCRIPTION\n -----------\n-In the first form, set the current branch head (`HEAD`) to __,\n-optionally modifying index and working tree to match.\n-The __/__ defaults to `HEAD` in all forms.\n-In the last three forms, copy entries from __ to the index.\n+`git reset` does either of the following:\n+\n+1. `git reset [] ` changes which commit HEAD points to. This makes\n+ it possible to undo various Git operations, for example commit, merge,\n+ rebase, and pull.\n+2. When you specify files or directories or pass `--patch`, `git reset` updates\n+ the staged version of the specified files.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n-- \n2.52.0.rc0.365.g9bf09b728d.dirty\n\n"},{"id":"532510","messageId":"89c87c14aabfe91489af4a7afa5246ec20776e0b.1766103827.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1766103827.git.ben.knoble+github@gmail.com","subject":"[PATCH v2 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-12-19T00:23:55Z","receivedAt":"2025-12-19T00:24:37Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there was some confusion about the differences\nbetween the modes, including:\n\n1. Sometimes it says \"index\" and sometimes \"index file\".\n Fix by replacing \"index file\" with \"index\".\n2. Many comments about not being able to understand what `--merge` does.\n Fix by mentioning obscure situations, since that seems to be what\n it's for. Most folks will use `git --abort`.\n3. Issues telling the difference between --soft and --mixed, as well as\n --keep. Leave --keep alone because I couldn't understand its use case,\n but change `--soft` / `--mixed` / `--hard` as follows:\n\n--mixed is the default, so put it first.\n\nDescribe --soft/--mixed/--hard with the following structure:\n\n* Start by saying what happens to the files in the working directory,\n because the thing users want to avoid most is irretrievably losing\n changes to their working directory files.\n* Then describe what happens to the staging area. Right now it seems to\n frame leaving the index alone as being a sort of neutral action.\n I think this is part of what's confusing users, because in Git when\n you update HEAD, Git almost always updates the index to match HEAD.\n So leaving the index unchanged while updating HEAD is actually quite\n unusual, and it deserves to be flagged.\n* Finally, give an example for --soft to explain a common use case.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------\n 1 file changed, 24 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 71e8f52430..6de0d524c3 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -24,42 +24,46 @@ DESCRIPTION\n the staged version of the specified files.\n \n `git reset [] []`::\n-\tThis form resets the current branch head to __ and\n-\tpossibly updates the index (resetting it to the tree of __) and\n-\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If __ is omitted,\n-\tdefaults to `--mixed`. The __ must be one of the following:\n+\tSet the current branch head (`HEAD`) to point at __.\n+\tDepending on __, also update the working directory and/or index\n+\tto match the contents of __.\n+\t__ defaults to `HEAD`.\n+\tBefore the operation, `ORIG_HEAD` is set to the tip of the current branch.\n++\n+The __ must be one of the following (default `--mixed`):\n +\n---\n-`--soft`::\n-\tDoes not touch the index file or the working tree at all (but\n-\tresets the head to __, just like all modes do). This leaves\n-\tall your changed files \"Changes to be committed\", as `git status`\n-\twould put it.\n \n+--\n `--mixed`::\n-\tResets the index but not the working tree (i.e., the changed files\n-\tare preserved but not marked for commit) and reports what has not\n-\tbeen updated. This is the default action.\n+\tLeaves your working directory unchanged.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n +\n If `-N` is specified, removed paths are marked as intent-to-add (see\n linkgit:git-add[1]).\n \n+`--soft`::\n+\tLeave your working tree files and the index unchanged.\n+\tFor example, if you have no staged changes, you can use\n+\t`git reset --soft HEAD~5; git commit`\n+\tto combine the last 5 commits into 1 commit. This works even with\n+\tchanges in the working tree, which are left untouched, but such usage\n+\tcan lead to confusion.\n+\n `--hard`::\n-\tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since __ are discarded. Any untracked files or\n-\tdirectories in the way of writing any tracked files are simply deleted.\n+\tOverwrites all files and directories with the version from __,\n+\tand may overwrite untracked files. Tracked files not in __ are\n+\tremoved so that the working tree matches __.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n \n `--merge`::\n+\tMainly exists to reset unmerged index entries, like those left behind by\n+\t`git am -3` or `git switch -m` in certain situations.\n \tResets the index and updates the files in the working tree that are\n \tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n \tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n-+\n-In other words, `--merge` does something like a `git read-tree -u -m `,\n-but carries forward unmerged index entries.\n \n `--keep`::\n \tResets index entries and updates files in the working tree that are\n-- \n2.52.0.rc0.365.g9bf09b728d.dirty\n\n"},{"id":"532511","messageId":"d6582dc53ca852ef01421d2dd2c446dadb731dad.1766103827.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1766103827.git.ben.knoble+github@gmail.com","subject":"[PATCH v2 4/4] doc: git-reset: clarify `git reset `","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-12-19T00:23:56Z","receivedAt":"2025-12-19T00:24:40Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- Continued confusion about the terms \"tree-ish\" and \"pathspec\"\n- The word \"hunks\" is confusing folks, use \"changes\" instead.\n- On the part about `git restore`, there were a few comments to the\n effect of \"wait, this doesn't actually update any files? What? Why?\"\n Be more direct that `git reset` does not update files: there's no\n obvious reason to suggest that folks use `git reset` followed by `git\n restore`, instead suggest just using `git restore`.\n\nContinue avoiding the use of the word \"reset\" to\ndescribe what \"git reset\" does.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 28 ++++++++++++----------------\n 1 file changed, 12 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 6de0d524c3..ab7f565286 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -81,29 +81,25 @@ linkgit:git-add[1]).\n \n `git reset [-q] [] [--] ...`::\n `git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n+\tFor all specified files or directories, set the staged version to\n+\tthe version from the given commit or tree (which defaults to `HEAD`).\n +\n This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n+`: it unstages all changes to the specified file(s) or\n+directories. This is equivalent to `git restore --staged ...`.\n +\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n+In this mode, `git reset` updates only the index (without updating the HEAD or\n+working tree files). If you want to update the files as well as the index\n+entries, use linkgit:git-restore[1].\n \n `git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n+\tInteractively select changes from the difference between the index\n+\tand the specified commit or tree (which defaults to `HEAD`).\n+\tThe chosen changes are added to the index.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+you can use it to selectively unstage changes. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to use the `--patch` option.\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n-- \n2.52.0.rc0.365.g9bf09b728d.dirty\n\n"},{"id":"532822","messageId":"xmqqwm24fsq4.fsf@gitster.g","threadId":"64347","inReplyTo":"d6582dc53ca852ef01421d2dd2c446dadb731dad.1766103827.git.ben.knoble+github@gmail.com","subject":"Re: [PATCH v2 4/4] doc: git-reset: clarify `git reset `","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-30T05:23:31Z","receivedAt":"2025-12-30T05:23:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> `git reset (--patch | -p) [] [--] [...]`::\n> -\tInteractively select hunks in the difference between the index\n> -\tand __ (defaults to `HEAD`). The chosen hunks are applied\n> -\tin reverse to the index.\n> +\tInteractively select changes from the difference between the index\n> +\tand the specified commit or tree (which defaults to `HEAD`).\n> +\tThe chosen changes are added to the index.\n\nThe previous iteration said \"changes are unstaged\", implying that\nthe changes are removed from the index. But now it says the changes\nare added to the index. Which one?\n\nI think neither is correct. I wasn't involved in the design of the\nbehaviour of \"reset -p\", but IIUC,\n\n git reset -p\n git reset -p HEAD\n\nshow \"git diff --cached HEAD\" (i.e., what damage you will cause if\nyou commit what is in the index), so chosen hunks will be reverted\nout of the index if you say \"y\" to \"reset -p\" prompt.\n\nOn the other hand, \n\n git reset -p COMMIT\n\nfor COMMIT that is not HEAD gives \"git diff -R --cached COMMIT\"\n(i.e., the changes to take you closer to the named commit), so\nchosen hunks will participate in the next commit if you commit after\ncompleting this \"reset -p\" session.\n\n The contents in the index are modified using the chosen hunks.\n\nis the best description I can come up with.\n\nThe actual prompt asks \"unstage this hunk?\" when operating against\nHEAD, while the prompt changes to \"apply this hunk to index?\" when\nopeating against a commit that is not HEAD, so it might be simpler\nnot to say anything about the direction of the application (i.e.,\nhow the chosen hunks are used to modify the index) in this\nparagraph, like the above example, may be a viable option.\n"},{"id":"532884","messageId":"CALnO6CDDqwC-YpL6c7Ed1yD+xBuzTxAZo867AUue7=iAo5adNQ@mail.gmail.com","threadId":"64347","inReplyTo":"xmqqwm24fsq4.fsf@gitster.g","subject":"Re: [PATCH v2 4/4] doc: git-reset: clarify `git reset `","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:32:44Z","receivedAt":"2026-01-01T22:32:55Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Dec 30, 2025 at 12:23 AM Junio C Hamano wrote:\n>\n> \"D. Ben Knoble\" writes:\n>\n> > `git reset (--patch | -p) [] [--] [...]`::\n> > - Interactively select hunks in the difference between the index\n> > - and __ (defaults to `HEAD`). The chosen hunks are applied\n> > - in reverse to the index.\n> > + Interactively select changes from the difference between the index\n> > + and the specified commit or tree (which defaults to `HEAD`).\n> > + The chosen changes are added to the index.\n>\n> The previous iteration said \"changes are unstaged\", implying that\n> the changes are removed from the index. But now it says the changes\n> are added to the index. Which one?\n\nAh, I think I really mean that _changes_ are added. The change might\nbe an addition (+) or subtraction (-) in patch terms, so some changes\nmay result in the index having fewer modifications relative to the\nworking tree or something. But it's not\nvery clear, and certainly a bit pedantic.\n\n> I think neither is correct. I wasn't involved in the design of the\n> behaviour of \"reset -p\", but IIUC,\n>\n> git reset -p\n> git reset -p HEAD\n>\n> show \"git diff --cached HEAD\" (i.e., what damage you will cause if\n> you commit what is in the index), so chosen hunks will be reverted\n> out of the index if you say \"y\" to \"reset -p\" prompt.\n\nIndeed. I was actually expecting to see the reverse hunks here, so I\nwas surprised to see the staged hunks.\n\n> On the other hand,\n>\n> git reset -p COMMIT\n>\n> for COMMIT that is not HEAD gives \"git diff -R --cached COMMIT\"\n> (i.e., the changes to take you closer to the named commit), so\n> chosen hunks will participate in the next commit if you commit after\n> completing this \"reset -p\" session.\n\nHm. I can see how this behaves nearly the opposite of the former. Yikes.\n\n> The contents in the index are modified using the chosen hunks.\n>\n> is the best description I can come up with.\n>\n> The actual prompt asks \"unstage this hunk?\" when operating against\n> HEAD, while the prompt changes to \"apply this hunk to index?\" when\n> opeating against a commit that is not HEAD, so it might be simpler\n> not to say anything about the direction of the application (i.e.,\n> how the chosen hunks are used to modify the index) in this\n> paragraph, like the above example, may be a viable option.\n\nYeah, I think so. Will send a new version with this update.\n"},{"id":"532886","messageId":"cover.1767307382.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1766103827.git.ben.knoble+github@gmail.com","subject":"[PATCH v3 0/4] doc: git-reset: clarify DESCRIPTION section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:43:55Z","receivedAt":"2026-01-01T22:44:23Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"This continues Julia Evans's excellent work updating the git-reset docs.\n\nChanges in v3:\n- Adjust \"git reset -p\" description per Junio's review\n\nChanges in v2:\n- Mostly address Junio's review while keeping to Julia's style (?),\n taking at a stab at a few gray areas.\n- I left alone the first patch, the commented-upon part of which is\n later rewritten anyway.\n\nv1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/\nv2: https://lore.kernel.org/git/cover.1766103827.git.ben.knoble+github@gmail.com/\nPublished-as: https://github.com/benknoble/git/tree/bk/je/doc-reset\nGenerated-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 '\n\nJulia Evans (4):\n doc: git-reset: reorder the forms\n doc: git-reset: clarify intro\n doc: git-reset: clarify `git reset [mode]`\n doc: git-reset: clarify `git reset `\n\n Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------\n 1 file changed, 54 insertions(+), 51 deletions(-)\n\nDiff-intervalle contre v2 :\n1: a558c5a868 = 1: a558c5a868 doc: git-reset: reorder the forms\n2: f90be8559f = 2: f90be8559f doc: git-reset: clarify intro\n3: 89c87c14aa = 3: 89c87c14aa doc: git-reset: clarify `git reset [mode]`\n4: d6582dc53c ! 4: 96566265d8 doc: git-reset: clarify `git reset `\n @@ Documentation/git-reset.adoc: linkgit:git-add[1]).\n -\tin reverse to the index.\n +\tInteractively select changes from the difference between the index\n +\tand the specified commit or tree (which defaults to `HEAD`).\n -+\tThe chosen changes are added to the index.\n ++\tThe index is modified using the chosen changes.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n -you can use it to selectively reset hunks. See the \"Interactive Mode\"\n\nbase-commit: f229982df19c327876ce7ded40f6efefe20da5d4\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"532885","messageId":"a558c5a8684639a2e888866a650357f54f29f2a6.1767307382.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767307382.git.ben.knoble+github@gmail.com","subject":"[PATCH v3 1/4] doc: git-reset: reorder the forms","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:43:56Z","receivedAt":"2026-01-01T22:44:24Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: three users commented that the `git reset [mode]`\nform is the one that they primarily use, and that they were suprised to\nsee it listed last.\n(\"I've never used git reset in any mode other than --hard\").\n\nMove it to be first, since the `git reset [mode]` form is what\n\"Reset current HEAD to the specified state\" at the beginning refers\nto, and because the `git reset [mode]` form is the only thing that\n`git reset` uniquely does, the others could also be done with\n`git restore`.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------\n 1 file changed, 29 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 3b9ba9aee9..9843682e81 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n SYNOPSIS\n --------\n [synopsis]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n git reset [-q] [] [--] ...\n git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n git reset (--patch | -p) [] [--] [...]\n-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from __ to the index.\n-In the last form, set the current branch head (`HEAD`) to __,\n+In the first form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n The __/__ defaults to `HEAD` in all forms.\n-\n-`git reset [-q] [] [--] ...`::\n-`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n-+\n-This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n-+\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n-\n-`git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n-+\n-This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+In the last three forms, copy entries from __ to the index.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n@@ -98,6 +72,32 @@ but carries forward unmerged index entries.\n \tthe submodules' `HEAD` to be detached at that commit.\n --\n \n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n+\tThese forms reset the index entries for all paths that match the\n+\t__ to their state at __. (It does not affect\n+\tthe working tree or the current branch.)\n++\n+This means that `git reset ` is the opposite of `git add\n+`. This command is equivalent to\n+`git restore [--source=] --staged ...`.\n++\n+After running `git reset ` to update the index entry, you can\n+use linkgit:git-restore[1] to check the contents out of the index to\n+the working tree. Alternatively, using linkgit:git-restore[1]\n+and specifying a commit with `--source`, you\n+can copy the contents of a path out of a commit to the index and to the\n+working tree in one go.\n+\n+`git reset (--patch | -p) [] [--] [...]`::\n+\tInteractively select hunks in the difference between the index\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n+\tin reverse to the index.\n++\n+This means that `git reset -p` is the opposite of `git add -p`, i.e.\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"532887","messageId":"f90be8559f7d1d8362077a6f888687ee8be063b4.1767307382.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767307382.git.ben.knoble+github@gmail.com","subject":"[PATCH v3 2/4] doc: git-reset: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:43:57Z","receivedAt":"2026-01-01T22:44:25Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there were several points of confusion:\n\n- What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n (\"I have no clue what the index is\", \"I've been using git for 20 years\n and still don't know what a tree-ish is\"). Avoid using these terms\n where it makes sense.\n- What \"optionally modifying index and working tree to match\" means\n (\"to match what?\" \"optionally based on what?\")\n Remove this from the intro, we can say it later when giving more\n details.\n- One user suggested that \"The / defaults to HEAD\n in all forms.\" should be repeated later on, since it's easy to miss.\n Instead say that HEAD is the default in each case later.\n\nAnother issue is that `git reset` consistently describes the action\nit does as \"Reset ...\", commands should not use their name to describe\nthemselves, and that the word \"mode\" is used to mean several different\nthings on this page.\n\nAddress these by being more clear about two use cases for `git reset`\n(\"to undo operations\" and \"to update staged files\"), and explaining what\nthe conditions are for each case instead of forcing the user to figure\nout the pattern is in first form vs the other 3 forms.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 9843682e81..71e8f52430 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -3,7 +3,7 @@ git-reset(1)\n \n NAME\n ----\n-git-reset - Reset current HEAD to the specified state\n+git-reset - Set HEAD or the index to a known state\n \n SYNOPSIS\n --------\n@@ -15,10 +15,13 @@ git reset (--patch | -p) [] [--] [...]\n \n DESCRIPTION\n -----------\n-In the first form, set the current branch head (`HEAD`) to __,\n-optionally modifying index and working tree to match.\n-The __/__ defaults to `HEAD` in all forms.\n-In the last three forms, copy entries from __ to the index.\n+`git reset` does either of the following:\n+\n+1. `git reset [] ` changes which commit HEAD points to. This makes\n+ it possible to undo various Git operations, for example commit, merge,\n+ rebase, and pull.\n+2. When you specify files or directories or pass `--patch`, `git reset` updates\n+ the staged version of the specified files.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"532888","messageId":"89c87c14aabfe91489af4a7afa5246ec20776e0b.1767307382.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767307382.git.ben.knoble+github@gmail.com","subject":"[PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:43:58Z","receivedAt":"2026-01-01T22:44:26Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there was some confusion about the differences\nbetween the modes, including:\n\n1. Sometimes it says \"index\" and sometimes \"index file\".\n Fix by replacing \"index file\" with \"index\".\n2. Many comments about not being able to understand what `--merge` does.\n Fix by mentioning obscure situations, since that seems to be what\n it's for. Most folks will use `git --abort`.\n3. Issues telling the difference between --soft and --mixed, as well as\n --keep. Leave --keep alone because I couldn't understand its use case,\n but change `--soft` / `--mixed` / `--hard` as follows:\n\n--mixed is the default, so put it first.\n\nDescribe --soft/--mixed/--hard with the following structure:\n\n* Start by saying what happens to the files in the working directory,\n because the thing users want to avoid most is irretrievably losing\n changes to their working directory files.\n* Then describe what happens to the staging area. Right now it seems to\n frame leaving the index alone as being a sort of neutral action.\n I think this is part of what's confusing users, because in Git when\n you update HEAD, Git almost always updates the index to match HEAD.\n So leaving the index unchanged while updating HEAD is actually quite\n unusual, and it deserves to be flagged.\n* Finally, give an example for --soft to explain a common use case.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------\n 1 file changed, 24 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 71e8f52430..6de0d524c3 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -24,42 +24,46 @@ DESCRIPTION\n the staged version of the specified files.\n \n `git reset [] []`::\n-\tThis form resets the current branch head to __ and\n-\tpossibly updates the index (resetting it to the tree of __) and\n-\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If __ is omitted,\n-\tdefaults to `--mixed`. The __ must be one of the following:\n+\tSet the current branch head (`HEAD`) to point at __.\n+\tDepending on __, also update the working directory and/or index\n+\tto match the contents of __.\n+\t__ defaults to `HEAD`.\n+\tBefore the operation, `ORIG_HEAD` is set to the tip of the current branch.\n++\n+The __ must be one of the following (default `--mixed`):\n +\n---\n-`--soft`::\n-\tDoes not touch the index file or the working tree at all (but\n-\tresets the head to __, just like all modes do). This leaves\n-\tall your changed files \"Changes to be committed\", as `git status`\n-\twould put it.\n \n+--\n `--mixed`::\n-\tResets the index but not the working tree (i.e., the changed files\n-\tare preserved but not marked for commit) and reports what has not\n-\tbeen updated. This is the default action.\n+\tLeaves your working directory unchanged.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n +\n If `-N` is specified, removed paths are marked as intent-to-add (see\n linkgit:git-add[1]).\n \n+`--soft`::\n+\tLeave your working tree files and the index unchanged.\n+\tFor example, if you have no staged changes, you can use\n+\t`git reset --soft HEAD~5; git commit`\n+\tto combine the last 5 commits into 1 commit. This works even with\n+\tchanges in the working tree, which are left untouched, but such usage\n+\tcan lead to confusion.\n+\n `--hard`::\n-\tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since __ are discarded. Any untracked files or\n-\tdirectories in the way of writing any tracked files are simply deleted.\n+\tOverwrites all files and directories with the version from __,\n+\tand may overwrite untracked files. Tracked files not in __ are\n+\tremoved so that the working tree matches __.\n+\tUpdates the index to match the new HEAD, so nothing will be staged.\n \n `--merge`::\n+\tMainly exists to reset unmerged index entries, like those left behind by\n+\t`git am -3` or `git switch -m` in certain situations.\n \tResets the index and updates the files in the working tree that are\n \tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n \tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n-+\n-In other words, `--merge` does something like a `git read-tree -u -m `,\n-but carries forward unmerged index entries.\n \n `--keep`::\n \tResets index entries and updates files in the working tree that are\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"532889","messageId":"96566265d89d62689388080283800712a182867c.1767307382.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767307382.git.ben.knoble+github@gmail.com","subject":"[PATCH v3 4/4] doc: git-reset: clarify `git reset `","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-01T22:43:59Z","receivedAt":"2026-01-01T22:44:26Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- Continued confusion about the terms \"tree-ish\" and \"pathspec\"\n- The word \"hunks\" is confusing folks, use \"changes\" instead.\n- On the part about `git restore`, there were a few comments to the\n effect of \"wait, this doesn't actually update any files? What? Why?\"\n Be more direct that `git reset` does not update files: there's no\n obvious reason to suggest that folks use `git reset` followed by `git\n restore`, instead suggest just using `git restore`.\n\nContinue avoiding the use of the word \"reset\" to\ndescribe what \"git reset\" does.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 28 ++++++++++++----------------\n 1 file changed, 12 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 6de0d524c3..770f08c7f8 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -81,29 +81,25 @@ linkgit:git-add[1]).\n \n `git reset [-q] [] [--] ...`::\n `git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n+\tFor all specified files or directories, set the staged version to\n+\tthe version from the given commit or tree (which defaults to `HEAD`).\n +\n This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n+`: it unstages all changes to the specified file(s) or\n+directories. This is equivalent to `git restore --staged ...`.\n +\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n+In this mode, `git reset` updates only the index (without updating the HEAD or\n+working tree files). If you want to update the files as well as the index\n+entries, use linkgit:git-restore[1].\n \n `git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n+\tInteractively select changes from the difference between the index\n+\tand the specified commit or tree (which defaults to `HEAD`).\n+\tThe index is modified using the chosen changes.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+you can use it to selectively unstage changes. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to use the `--patch` option.\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"532919","messageId":"5953760.DvuYhMxLoT@piment-oiseau","threadId":"64347","inReplyTo":"f90be8559f7d1d8362077a6f888687ee8be063b4.1767307382.git.ben.knoble+github@gmail.com","subject":"Re: [PATCH v3 2/4] doc: git-reset: clarify intro","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-01-02T13:49:45Z","receivedAt":"2026-01-02T13:56:24Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le jeudi 1 janvier 2026, 23:43:57 heure normale d’Europe centrale D. Ben \nKnoble a écrit :\n> From: Julia Evans \n> \n> From user feedback, there were several points of confusion:\n> \n> - What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n> (\"I have no clue what the index is\", \"I've been using git for 20 years\n> and still don't know what a tree-ish is\"). Avoid using these terms\n> where it makes sense.\n> - What \"optionally modifying index and working tree to match\" means\n> (\"to match what?\" \"optionally based on what?\")\n> Remove this from the intro, we can say it later when giving more\n> details.\n> - One user suggested that \"The / defaults to HEAD\n> in all forms.\" should be repeated later on, since it's easy to miss.\n> Instead say that HEAD is the default in each case later.\n> \n> Another issue is that `git reset` consistently describes the action\n> it does as \"Reset ...\", commands should not use their name to describe\n> themselves, and that the word \"mode\" is used to mean several different\n> things on this page.\n> \n> Address these by being more clear about two use cases for `git reset`\n> (\"to undo operations\" and \"to update staged files\"), and explaining what\n> the conditions are for each case instead of forcing the user to figure\n> out the pattern is in first form vs the other 3 forms.\n> \n> Signed-off-by: Julia Evans \n> Signed-off-by: Junio C Hamano \n> Signed-off-by: D. Ben Knoble \n> ---\n> Documentation/git-reset.adoc | 13 ++++++++-----\n> 1 file changed, 8 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n> index 9843682e81..71e8f52430 100644\n> --- a/Documentation/git-reset.adoc\n> +++ b/Documentation/git-reset.adoc\n> @@ -3,7 +3,7 @@ git-reset(1)\n\nThere are `HEAD` that passed through the style checks.\n\n> \n> NAME\n> ----\n> -git-reset - Reset current HEAD to the specified state\n> +git-reset - Set HEAD or the index to a known state\n> \n\nHere\n\n> SYNOPSIS\n> --------\n> @@ -15,10 +15,13 @@ git reset (--patch | -p) [] [--] \n[...]\n> \n> DESCRIPTION\n> -----------\n> -In the first form, set the current branch head (`HEAD`) to __,\n> -optionally modifying index and working tree to match.\n> -The __/__ defaults to `HEAD` in all forms.\n> -In the last three forms, copy entries from __ to the index.\n> +`git reset` does either of the following:\n> +\n> +1. `git reset [] ` changes which commit HEAD points to. This \nmakes\n\nAnd here.\n\n> + it possible to undo various Git operations, for example commit, merge,\n> + rebase, and pull.\n> +2. When you specify files or directories or pass `--patch`, `git reset` \nupdates\n> + the staged version of the specified files.\n> \n> `git reset [] []`::\n> \tThis form resets the current branch head to __ and\n\nThanks\n\n\n"},{"id":"532920","messageId":"1943073.tdWV9SEqCh@piment-oiseau","threadId":"64347","inReplyTo":"89c87c14aabfe91489af4a7afa5246ec20776e0b.1767307382.git.ben.knoble+github@gmail.com","subject":"Re: [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2026-01-02T14:28:09Z","receivedAt":"2026-01-02T14:28:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Thursday, 1 January 2026 23:43:58 CET D. Ben Knoble wrote:\n> From: Julia Evans \n> \n> From user feedback, there was some confusion about the differences\n> between the modes, including:\n> \n> 1. Sometimes it says \"index\" and sometimes \"index file\".\n> Fix by replacing \"index file\" with \"index\".\n> 2. Many comments about not being able to understand what `--merge` does.\n> Fix by mentioning obscure situations, since that seems to be what\n> it's for. Most folks will use `git --abort`.\n> 3. Issues telling the difference between --soft and --mixed, as well as\n> --keep. Leave --keep alone because I couldn't understand its use case,\n> but change `--soft` / `--mixed` / `--hard` as follows:\n> \n> --mixed is the default, so put it first.\n> \n> Describe --soft/--mixed/--hard with the following structure:\n> \n> * Start by saying what happens to the files in the working directory,\n> because the thing users want to avoid most is irretrievably losing\n> changes to their working directory files.\n> * Then describe what happens to the staging area. Right now it seems to\n> frame leaving the index alone as being a sort of neutral action.\n> I think this is part of what's confusing users, because in Git when\n> you update HEAD, Git almost always updates the index to match HEAD.\n> So leaving the index unchanged while updating HEAD is actually quite\n> unusual, and it deserves to be flagged.\n> * Finally, give an example for --soft to explain a common use case.\n> \n> Signed-off-by: Julia Evans \n> Signed-off-by: Junio C Hamano \n> Signed-off-by: D. Ben Knoble \n> ---\n> Documentation/git-reset.adoc | 44 ++++++++++++++++++++----------------\n> 1 file changed, 24 insertions(+), 20 deletions(-)\n> \n> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\n> index 71e8f52430..6de0d524c3 100644\n> --- a/Documentation/git-reset.adoc\n> +++ b/Documentation/git-reset.adoc\n> @@ -24,42 +24,46 @@ DESCRIPTION\n> the staged version of the specified files.\n> \n> `git reset [] []`::\n> -\tThis form resets the current branch head to __ and\n> -\tpossibly updates the index (resetting it to the tree of __) \nand\n> -\tthe working tree depending on __. Before the operation, \n`ORIG_HEAD`\n> -\tis set to the tip of the current branch. If __ is omitted,\n> -\tdefaults to `--mixed`. The __ must be one of the following:\n> +\tSet the current branch head (`HEAD`) to point at __.\n> +\tDepending on __, also update the working directory and/or \nindex\n> +\tto match the contents of __.\n> +\t__ defaults to `HEAD`.\n> +\tBefore the operation, `ORIG_HEAD` is set to the tip of the current \nbranch.\n> ++\n> +The __ must be one of the following (default `--mixed`):\n> +\n> ---\n> -`--soft`::\n> -\tDoes not touch the index file or the working tree at all (but\n> -\tresets the head to __, just like all modes do). This leaves\n> -\tall your changed files \"Changes to be committed\", as `git status`\n> -\twould put it.\n> \n> +--\n> `--mixed`::\n> -\tResets the index but not the working tree (i.e., the changed files\n> -\tare preserved but not marked for commit) and reports what has not\n> -\tbeen updated. This is the default action.\n> +\tLeaves your working directory unchanged.\n> +\tUpdates the index to match the new HEAD, so nothing will be staged.\n\nPlease use imperative mood here, and use `HEAD`.\n\n> +\n> If `-N` is specified, removed paths are marked as intent-to-add (see\n> linkgit:git-add[1]).\n> \n> +`--soft`::\n> +\tLeave your working tree files and the index unchanged.\n> +\tFor example, if you have no staged changes, you can use\n> +\t`git reset --soft HEAD~5; git commit`\n> +\tto combine the last 5 commits into 1 commit. This works even with\n> +\tchanges in the working tree, which are left untouched, but such \nusage\n> +\tcan lead to confusion.\n> +\n> `--hard`::\n> -\tResets the index and working tree. Any changes to tracked files in \nthe\n> -\tworking tree since __ are discarded. Any untracked files or\n> -\tdirectories in the way of writing any tracked files are simply \ndeleted.\n> +\tOverwrites all files and directories with the version from \n__,\n> +\tand may overwrite untracked files. Tracked files not in __ \nare\n> +\tremoved so that the working tree matches __.\n> +\tUpdates the index to match the new HEAD, so nothing will be staged.\n\nHere too.\n\n> \n> `--merge`::\n> +\tMainly exists to reset unmerged index entries, like those left \nbehind by\n> +\t`git am -3` or `git switch -m` in certain situations.\n\nPersonal preference, please insert this context sentence after the main \ndescription of the action. Could you also change the mood of the description \nto imperative?\n\n\n> \tResets the index and updates the files in the working tree that are\n> \tdifferent between __ and `HEAD`, but keeps those which are\n> \tdifferent between the index and working tree (i.e. which have \nchanges\n> \twhich have not been added).\n> \tIf a file that is different between __ and the index has\n> \tunstaged changes, reset is aborted.\n> -+\n> -In other words, `--merge` does something like a `git read-tree -u -m \n`,\n> -but carries forward unmerged index entries.\n> \n> `--keep`::\n> \tResets index entries and updates files in the working tree that are\n\nThanks\n\n\n\n"},{"id":"533077","messageId":"cover.1767649692.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767307382.git.ben.knoble+github@gmail.com","subject":"[PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-05T21:48:14Z","receivedAt":"2026-01-05T21:48:58Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"This continues Julia Evans's excellent work updating the git-reset docs.\n\nChanges in v4:\n- Adjust wording per Jean-Noël Avila's review\n\nChanges in v3:\n- Adjust \"git reset -p\" description per Junio's review\n\nChanges in v2:\n- Mostly address Junio's review while keeping to Julia's style (?),\n taking at a stab at a few gray areas.\n- I left alone the first patch, the commented-upon part of which is\n later rewritten anyway.\n\nv1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/\nv2: https://lore.kernel.org/git/cover.1766103827.git.ben.knoble+github@gmail.com/\nv3: https://lore.kernel.org/git/cover.1767307382.git.ben.knoble+github@gmail.com/\nPublished-as: https://github.com/benknoble/git/tree/bk/je/doc-reset\n\nJulia Evans (4):\n doc: git-reset: reorder the forms\n doc: git-reset: clarify intro\n doc: git-reset: clarify `git reset [mode]`\n doc: git-reset: clarify `git reset `\n\n Documentation/git-reset.adoc | 111 ++++++++++++++++++-----------------\n 1 file changed, 57 insertions(+), 54 deletions(-)\n\nDiff-intervalle contre v3 :\n1: a558c5a868 = 1: a558c5a868 doc: git-reset: reorder the forms\n2: f90be8559f ! 2: 3fc46c7158 doc: git-reset: clarify intro\n @@ Documentation/git-reset.adoc: git-reset(1)\n NAME\n ----\n -git-reset - Reset current HEAD to the specified state\n -+git-reset - Set HEAD or the index to a known state\n ++git-reset - Set `HEAD` or the index to a known state\n \n SYNOPSIS\n --------\n @@ Documentation/git-reset.adoc: git reset (--patch | -p) [] [--] [_ to the index.\n +`git reset` does either of the following:\n +\n -+1. `git reset [] ` changes which commit HEAD points to. This makes\n -+ it possible to undo various Git operations, for example commit, merge,\n ++1. `git reset [] ` changes which commit `HEAD` points to. This\n ++ makes it possible to undo various Git operations, for example commit, merge,\n + rebase, and pull.\n +2. When you specify files or directories or pass `--patch`, `git reset` updates\n + the staged version of the specified files.\n3: 89c87c14aa ! 3: 0ca9fcf943 doc: git-reset: clarify `git reset [mode]`\n @@ Documentation/git-reset.adoc: DESCRIPTION\n -\tResets the index but not the working tree (i.e., the changed files\n -\tare preserved but not marked for commit) and reports what has not\n -\tbeen updated. This is the default action.\n -+\tLeaves your working directory unchanged.\n -+\tUpdates the index to match the new HEAD, so nothing will be staged.\n ++\tLeave your working directory unchanged.\n ++\tUpdate the index to match the new `HEAD`, so nothing will be staged.\n +\n - If `-N` is specified, removed paths are marked as intent-to-add (see\n +-If `-N` is specified, removed paths are marked as intent-to-add (see\n ++If `-N` is specified, mark removed paths as intent-to-add (see\n linkgit:git-add[1]).\n \n +`--soft`::\n @@ Documentation/git-reset.adoc: DESCRIPTION\n -\tResets the index and working tree. Any changes to tracked files in the\n -\tworking tree since __ are discarded. Any untracked files or\n -\tdirectories in the way of writing any tracked files are simply deleted.\n -+\tOverwrites all files and directories with the version from __,\n ++\tOverwrite all files and directories with the version from __,\n +\tand may overwrite untracked files. Tracked files not in __ are\n +\tremoved so that the working tree matches __.\n -+\tUpdates the index to match the new HEAD, so nothing will be staged.\n ++\tUpdate the index to match the new `HEAD`, so nothing will be staged.\n \n `--merge`::\n -+\tMainly exists to reset unmerged index entries, like those left behind by\n -+\t`git am -3` or `git switch -m` in certain situations.\n - \tResets the index and updates the files in the working tree that are\n - \tdifferent between __ and `HEAD`, but keeps those which are\n +-\tResets the index and updates the files in the working tree that are\n +-\tdifferent between __ and `HEAD`, but keeps those which are\n ++\tReset the index and update the files in the working tree that are\n ++\tdifferent between __ and `HEAD`, but keep those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n ++\tMainly exists to reset unmerged index entries, like those left behind by\n ++\t`git am -3` or `git switch -m` in certain situations.\n \tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n -+\n4: 96566265d8 ! 4: accf7a0673 doc: git-reset: clarify `git reset `\n @@ Documentation/git-reset.adoc: linkgit:git-add[1]).\n -and specifying a commit with `--source`, you\n -can copy the contents of a path out of a commit to the index and to the\n -working tree in one go.\n -+In this mode, `git reset` updates only the index (without updating the HEAD or\n ++In this mode, `git reset` updates only the index (without updating the `HEAD` or\n +working tree files). If you want to update the files as well as the index\n +entries, use linkgit:git-restore[1].\n \n\nbase-commit: f229982df19c327876ce7ded40f6efefe20da5d4\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"533078","messageId":"a558c5a8684639a2e888866a650357f54f29f2a6.1767649692.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767649692.git.ben.knoble+github@gmail.com","subject":"[PATCH v4 1/4] doc: git-reset: reorder the forms","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-05T21:48:15Z","receivedAt":"2026-01-05T21:48:59Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback: three users commented that the `git reset [mode]`\nform is the one that they primarily use, and that they were suprised to\nsee it listed last.\n(\"I've never used git reset in any mode other than --hard\").\n\nMove it to be first, since the `git reset [mode]` form is what\n\"Reset current HEAD to the specified state\" at the beginning refers\nto, and because the `git reset [mode]` form is the only thing that\n`git reset` uniquely does, the others could also be done with\n`git restore`.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 58 ++++++++++++++++++------------------\n 1 file changed, 29 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 3b9ba9aee9..9843682e81 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state\n SYNOPSIS\n --------\n [synopsis]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n git reset [-q] [] [--] ...\n git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n git reset (--patch | -p) [] [--] [...]\n-git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from __ to the index.\n-In the last form, set the current branch head (`HEAD`) to __,\n+In the first form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n The __/__ defaults to `HEAD` in all forms.\n-\n-`git reset [-q] [] [--] ...`::\n-`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n-+\n-This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n-+\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n-\n-`git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n-+\n-This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+In the last three forms, copy entries from __ to the index.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n@@ -98,6 +72,32 @@ but carries forward unmerged index entries.\n \tthe submodules' `HEAD` to be detached at that commit.\n --\n \n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n+\tThese forms reset the index entries for all paths that match the\n+\t__ to their state at __. (It does not affect\n+\tthe working tree or the current branch.)\n++\n+This means that `git reset ` is the opposite of `git add\n+`. This command is equivalent to\n+`git restore [--source=] --staged ...`.\n++\n+After running `git reset ` to update the index entry, you can\n+use linkgit:git-restore[1] to check the contents out of the index to\n+the working tree. Alternatively, using linkgit:git-restore[1]\n+and specifying a commit with `--source`, you\n+can copy the contents of a path out of a commit to the index and to the\n+working tree in one go.\n+\n+`git reset (--patch | -p) [] [--] [...]`::\n+\tInteractively select hunks in the difference between the index\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n+\tin reverse to the index.\n++\n+This means that `git reset -p` is the opposite of `git add -p`, i.e.\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"533079","messageId":"3fc46c7158fdfb5fea5616bebb713e564d843d8e.1767649692.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767649692.git.ben.knoble+github@gmail.com","subject":"[PATCH v4 2/4] doc: git-reset: clarify intro","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-05T21:48:16Z","receivedAt":"2026-01-05T21:49:00Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there were several points of confusion:\n\n- What \"tree-ish\", \"entries\", \"working tree\", \"HEAD\", and \"index\" mean\n (\"I have no clue what the index is\", \"I've been using git for 20 years\n and still don't know what a tree-ish is\"). Avoid using these terms\n where it makes sense.\n- What \"optionally modifying index and working tree to match\" means\n (\"to match what?\" \"optionally based on what?\")\n Remove this from the intro, we can say it later when giving more\n details.\n- One user suggested that \"The / defaults to HEAD\n in all forms.\" should be repeated later on, since it's easy to miss.\n Instead say that HEAD is the default in each case later.\n\nAnother issue is that `git reset` consistently describes the action\nit does as \"Reset ...\", commands should not use their name to describe\nthemselves, and that the word \"mode\" is used to mean several different\nthings on this page.\n\nAddress these by being more clear about two use cases for `git reset`\n(\"to undo operations\" and \"to update staged files\"), and explaining what\nthe conditions are for each case instead of forcing the user to figure\nout the pattern is in first form vs the other 3 forms.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 9843682e81..91dc6e6278 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -3,7 +3,7 @@ git-reset(1)\n \n NAME\n ----\n-git-reset - Reset current HEAD to the specified state\n+git-reset - Set `HEAD` or the index to a known state\n \n SYNOPSIS\n --------\n@@ -15,10 +15,13 @@ git reset (--patch | -p) [] [--] [...]\n \n DESCRIPTION\n -----------\n-In the first form, set the current branch head (`HEAD`) to __,\n-optionally modifying index and working tree to match.\n-The __/__ defaults to `HEAD` in all forms.\n-In the last three forms, copy entries from __ to the index.\n+`git reset` does either of the following:\n+\n+1. `git reset [] ` changes which commit `HEAD` points to. This\n+ makes it possible to undo various Git operations, for example commit, merge,\n+ rebase, and pull.\n+2. When you specify files or directories or pass `--patch`, `git reset` updates\n+ the staged version of the specified files.\n \n `git reset [] []`::\n \tThis form resets the current branch head to __ and\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"533080","messageId":"0ca9fcf943653013ec2e4c6e1b3d625ea37adc26.1767649692.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767649692.git.ben.knoble+github@gmail.com","subject":"[PATCH v4 3/4] doc: git-reset: clarify `git reset [mode]`","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-05T21:48:17Z","receivedAt":"2026-01-05T21:49:01Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback, there was some confusion about the differences\nbetween the modes, including:\n\n1. Sometimes it says \"index\" and sometimes \"index file\".\n Fix by replacing \"index file\" with \"index\".\n2. Many comments about not being able to understand what `--merge` does.\n Fix by mentioning obscure situations, since that seems to be what\n it's for. Most folks will use `git --abort`.\n3. Issues telling the difference between --soft and --mixed, as well as\n --keep. Leave --keep alone because I couldn't understand its use case,\n but change `--soft` / `--mixed` / `--hard` as follows:\n\n--mixed is the default, so put it first.\n\nDescribe --soft/--mixed/--hard with the following structure:\n\n* Start by saying what happens to the files in the working directory,\n because the thing users want to avoid most is irretrievably losing\n changes to their working directory files.\n* Then describe what happens to the staging area. Right now it seems to\n frame leaving the index alone as being a sort of neutral action.\n I think this is part of what's confusing users, because in Git when\n you update HEAD, Git almost always updates the index to match HEAD.\n So leaving the index unchanged while updating HEAD is actually quite\n unusual, and it deserves to be flagged.\n* Finally, give an example for --soft to explain a common use case.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 50 +++++++++++++++++++-----------------\n 1 file changed, 27 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 91dc6e6278..37c868ae24 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -24,42 +24,46 @@ DESCRIPTION\n the staged version of the specified files.\n \n `git reset [] []`::\n-\tThis form resets the current branch head to __ and\n-\tpossibly updates the index (resetting it to the tree of __) and\n-\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If __ is omitted,\n-\tdefaults to `--mixed`. The __ must be one of the following:\n+\tSet the current branch head (`HEAD`) to point at __.\n+\tDepending on __, also update the working directory and/or index\n+\tto match the contents of __.\n+\t__ defaults to `HEAD`.\n+\tBefore the operation, `ORIG_HEAD` is set to the tip of the current branch.\n++\n+The __ must be one of the following (default `--mixed`):\n +\n---\n-`--soft`::\n-\tDoes not touch the index file or the working tree at all (but\n-\tresets the head to __, just like all modes do). This leaves\n-\tall your changed files \"Changes to be committed\", as `git status`\n-\twould put it.\n \n+--\n `--mixed`::\n-\tResets the index but not the working tree (i.e., the changed files\n-\tare preserved but not marked for commit) and reports what has not\n-\tbeen updated. This is the default action.\n+\tLeave your working directory unchanged.\n+\tUpdate the index to match the new `HEAD`, so nothing will be staged.\n +\n-If `-N` is specified, removed paths are marked as intent-to-add (see\n+If `-N` is specified, mark removed paths as intent-to-add (see\n linkgit:git-add[1]).\n \n+`--soft`::\n+\tLeave your working tree files and the index unchanged.\n+\tFor example, if you have no staged changes, you can use\n+\t`git reset --soft HEAD~5; git commit`\n+\tto combine the last 5 commits into 1 commit. This works even with\n+\tchanges in the working tree, which are left untouched, but such usage\n+\tcan lead to confusion.\n+\n `--hard`::\n-\tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since __ are discarded. Any untracked files or\n-\tdirectories in the way of writing any tracked files are simply deleted.\n+\tOverwrite all files and directories with the version from __,\n+\tand may overwrite untracked files. Tracked files not in __ are\n+\tremoved so that the working tree matches __.\n+\tUpdate the index to match the new `HEAD`, so nothing will be staged.\n \n `--merge`::\n-\tResets the index and updates the files in the working tree that are\n-\tdifferent between __ and `HEAD`, but keeps those which are\n+\tReset the index and update the files in the working tree that are\n+\tdifferent between __ and `HEAD`, but keep those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n+\tMainly exists to reset unmerged index entries, like those left behind by\n+\t`git am -3` or `git switch -m` in certain situations.\n \tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n-+\n-In other words, `--merge` does something like a `git read-tree -u -m `,\n-but carries forward unmerged index entries.\n \n `--keep`::\n \tResets index entries and updates files in the working tree that are\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"533081","messageId":"accf7a0673358d4724e4944117a382494404deb1.1767649692.git.ben.knoble+github@gmail.com","threadId":"64347","inReplyTo":"cover.1767649692.git.ben.knoble+github@gmail.com","subject":"[PATCH v4 4/4] doc: git-reset: clarify `git reset `","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2026-01-05T21:48:18Z","receivedAt":"2026-01-05T21:49:02Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: Julia Evans \n\nFrom user feedback:\n\n- Continued confusion about the terms \"tree-ish\" and \"pathspec\"\n- The word \"hunks\" is confusing folks, use \"changes\" instead.\n- On the part about `git restore`, there were a few comments to the\n effect of \"wait, this doesn't actually update any files? What? Why?\"\n Be more direct that `git reset` does not update files: there's no\n obvious reason to suggest that folks use `git reset` followed by `git\n restore`, instead suggest just using `git restore`.\n\nContinue avoiding the use of the word \"reset\" to\ndescribe what \"git reset\" does.\n\nSigned-off-by: Julia Evans \nSigned-off-by: Junio C Hamano \nSigned-off-by: D. Ben Knoble \n---\n Documentation/git-reset.adoc | 28 ++++++++++++----------------\n 1 file changed, 12 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 37c868ae24..5023b50699 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -81,29 +81,25 @@ linkgit:git-add[1]).\n \n `git reset [-q] [] [--] ...`::\n `git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n-\tThese forms reset the index entries for all paths that match the\n-\t__ to their state at __. (It does not affect\n-\tthe working tree or the current branch.)\n+\tFor all specified files or directories, set the staged version to\n+\tthe version from the given commit or tree (which defaults to `HEAD`).\n +\n This means that `git reset ` is the opposite of `git add\n-`. This command is equivalent to\n-`git restore [--source=] --staged ...`.\n+`: it unstages all changes to the specified file(s) or\n+directories. This is equivalent to `git restore --staged ...`.\n +\n-After running `git reset ` to update the index entry, you can\n-use linkgit:git-restore[1] to check the contents out of the index to\n-the working tree. Alternatively, using linkgit:git-restore[1]\n-and specifying a commit with `--source`, you\n-can copy the contents of a path out of a commit to the index and to the\n-working tree in one go.\n+In this mode, `git reset` updates only the index (without updating the `HEAD` or\n+working tree files). If you want to update the files as well as the index\n+entries, use linkgit:git-restore[1].\n \n `git reset (--patch | -p) [] [--] [...]`::\n-\tInteractively select hunks in the difference between the index\n-\tand __ (defaults to `HEAD`). The chosen hunks are applied\n-\tin reverse to the index.\n+\tInteractively select changes from the difference between the index\n+\tand the specified commit or tree (which defaults to `HEAD`).\n+\tThe index is modified using the chosen changes.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the \"Interactive Mode\"\n-section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n+you can use it to selectively unstage changes. See the \"Interactive Mode\"\n+section of linkgit:git-add[1] to learn how to use the `--patch` option.\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n-- \n2.52.0.rc0.426.g1df11fb20d.dirty\n\n"},{"id":"533180","messageId":"xmqqfr8ihya4.fsf@gitster.g","threadId":"64347","inReplyTo":"cover.1767649692.git.ben.knoble+github@gmail.com","subject":"Re: [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-01-07T03:55:31Z","receivedAt":"2026-01-07T03:55:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n> This continues Julia Evans's excellent work updating the git-reset docs.\n>\n> Changes in v4:\n> - Adjust wording per Jean-Noël Avila's review\n>\n> base-commit: f229982df19c327876ce7ded40f6efefe20da5d4\n\nLooking good. Shall we mark it for 'next'?\n"}]}