kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

doc: git-reset: clarify `git reset <pathspec>` 

>From user feedback:

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

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

Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
seen
Julia Evans 2025-10-17 20:05:58 +00:00 committed by Junio C Hamano
parent 84aed17da6
commit 0b9583f872
1 changed files with 11 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Documentation/git-reset.adoc
View File

@ -79,29 +79,24 @@ linkgit:git-add[1]).


`git reset [-q] [<tree-ish>] [--] <pathspec>...`:: `git reset [-q] [<tree-ish>] [--] <pathspec>...`::
`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`:: `git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
These forms reset the index entries for all paths that match the For all specified files or directories, set the staged version to
_<pathspec>_ to their state at _<tree-ish>_. (It does not affect the version from the given commit or tree (which defaults to `HEAD`).
the working tree or the current branch.)
+ +
This means that `git reset <pathspec>` is the opposite of `git add This means that `git reset <pathspec>` is the opposite of `git add
<pathspec>`. This command is equivalent to <pathspec>`: it unstages all changes to the specified file(s) or
`git restore [--source=<tree-ish>] --staged <pathspec>...`. directories. This is equivalent to `git restore --staged <pathspec>...`.
+ +
After running `git reset <pathspec>` to update the index entry, you can `git reset` only modifies the index: use linkgit:git-restore[1] instead
use linkgit:git-restore[1] to check the contents out of the index to if you'd like to also update the file in your working directory.
the working tree. Alternatively, using linkgit:git-restore[1]
and specifying a commit with `--source`, you
can copy the contents of a path out of a commit to the index and to the
working tree in one go.


`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`:: `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
Interactively select hunks in the difference between the index Interactively select changes from the difference between the index
and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied and the specified commit or tree (which defaults to `HEAD`).
in reverse to the index. The chosen changes are unstaged.
+ +
This means that `git reset -p` is the opposite of `git add -p`, i.e. This means that `git reset -p` is the opposite of `git add -p`, i.e.
you can use it to selectively reset hunks. See the "Interactive Mode" you can use it to selectively unstage changes. See the "Interactive Mode"
section of linkgit:git-add[1] to learn how to operate the `--patch` mode. section of linkgit:git-add[1] to learn how to use the `--patch` option.


See "Reset, restore and revert" in linkgit:git[1] for the differences See "Reset, restore and revert" in linkgit:git[1] for the differences
between the three commands. between the three commands.