]> git.ipfire.org Git - thirdparty/git.git/commit
doc: git-reset: clarify `git reset [mode]`
authorJulia Evans <julia@jvns.ca>
Mon, 5 Jan 2026 21:48:17 +0000 (16:48 -0500)
committerJunio C Hamano <gitster@pobox.com>
Mon, 5 Jan 2026 23:10:14 +0000 (08:10 +0900)
commit7fb080a790b6410f8e36dbc10c5d9be0ff47ce98
tree0da1e49c3b186268a8f3197a5fb0e3f45f7a0406
parent296834217d61b03e543863bd250c56a302a7ead2
doc: git-reset: clarify `git reset [mode]`

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

1. Sometimes it says "index" and sometimes "index file".
   Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
   Fix by mentioning obscure situations, since that seems to be what
   it's for. Most folks will use `git <cmd> --abort`.
3. Issues telling the difference between --soft and --mixed, as well as
   --keep. Leave --keep alone because I couldn't understand its use case,
   but change `--soft` / `--mixed` / `--hard` as follows:

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

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-reset.adoc