]> git.ipfire.org Git - thirdparty/git.git/commit
doc: git-reset: clarify `git reset [mode]`
authorJulia Evans <julia@jvns.ca>
Fri, 19 Dec 2025 00:23:55 +0000 (19:23 -0500)
committerJunio C Hamano <gitster@pobox.com>
Fri, 19 Dec 2025 09:02:35 +0000 (18:02 +0900)
commit1dcdab83f7ff2fe49629314f7d8297211e65d948
treeb44dc2b6ecc878b74d56c82ebac3ea5e4994ec03
parent22161696dd0cd7567505f914d17e007681c4b6ff
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