This continues Julia Evans's excellent work updating the git-reset docs.
Changes in v2:
- Mostly address Junio's review while keeping to Julia's style (?),
taking at a stab at a few gray areas.
- I left alone the first patch, the commented-upon part of which is
later rewritten anyway.
v1: https://lore.kernel.org/git/pull.1991.git.1760731558.gitgitgadget@gmail.com/
Published-as: https://github.com/benknoble/git/tree/bk/je/doc-reset
Julia Evans (4):
doc: git-reset: reorder the forms
doc: git-reset: clarify intro
doc: git-reset: clarify `git reset [mode]`
doc: git-reset: clarify `git reset <pathspec>`
Documentation/git-reset.adoc | 105 ++++++++++++++++++-----------------
1 file changed, 54 insertions(+), 51 deletions(-)
Diff-intervalle contre v1 :
1: 5074fbf4ea ! 1: a558c5a868 doc: git-reset: reorder the forms
@@ Metadata
## Commit message ##
doc: git-reset: reorder the forms
- >From user feedback: three users commented that the `git reset [mode]`
+ From user feedback: three users commented that the `git reset [mode]`
form is the one that they primarily use, and that they were suprised to
see it listed last.
("I've never used git reset in any mode other than --hard").
2: c7049edf39 ! 2: f90be8559f doc: git-reset: clarify intro
@@ Metadata
## Commit message ##
doc: git-reset: clarify intro
- >From user feedback, there were several points of confusion:
+ From user feedback, there were several points of confusion:
- What "tree-ish", "entries", "working tree", "HEAD", and "index" mean
("I have no clue what the index is", "I've been using git for 20 years
@@ Documentation/git-reset.adoc: git-reset(1)
NAME
----
-git-reset - Reset current HEAD to the specified state
-+git-reset - Set HEAD to point at the specified commit
++git-reset - Set HEAD or the index to a known state
SYNOPSIS
--------
@@ Documentation/git-reset.adoc: git reset (--patch | -p) [<tree-ish>] [--] [<paths
-optionally modifying index and working tree to match.
-The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
-In the last three forms, copy entries from _<tree-ish>_ to the index.
-+`git reset [<mode>] <commit>` changes which commit HEAD points to.
-+This makes it possible to undo various Git operations, for example
-+commit, merge, rebase, and pull.
++`git reset` does either of the following:
+
-+However, when you specify files or directories or pass `--patch`,
-+`git reset` will instead update the staged version of the specified
-+files without updating HEAD.
++1. `git reset [<mode>] <commit>` changes which commit HEAD points to. This makes
++ it possible to undo various Git operations, for example commit, merge,
++ rebase, and pull.
++2. When you specify files or directories or pass `--patch`, `git reset` updates
++ the staged version of the specified files.
`git reset [<mode>] [<commit>]`::
This form resets the current branch head to _<commit>_ and
3: 84aed17da6 ! 3: 89c87c14aa doc: git-reset: clarify `git reset [mode]`
@@ Metadata
## Commit message ##
doc: git-reset: clarify `git reset [mode]`
- >From user feedback, there was some confusion about the differences
+ From user feedback, there was some confusion about the differences
between the modes, including:
1. Sometimes it says "index" and sometimes "index file".
Fix by replacing "index file" with "index".
2. Many comments about not being able to understand what `--merge` does.
- Fix by mentioning `git merge --abort` since my best guess is that
- most folks want to use that instead of `git reset --merge`.
+ Fix by mentioning obscure situations, since that seems to be what
+ it's for. Most folks will use `git <cmd> --abort`.
3. Issues telling the difference between --soft and --mixed, as well as
--keep. Leave --keep alone because I couldn't understand its use case,
but change `--soft` / `--mixed` / `--hard` as follows:
@@ Commit message
Signed-off-by: Junio C Hamano <gitster@pobox.com>
## Documentation/git-reset.adoc ##
-@@ Documentation/git-reset.adoc: However, when you specify files or directories or pass `--patch`,
- files without updating HEAD.
+@@ Documentation/git-reset.adoc: DESCRIPTION
+ the staged version of the specified files.
`git reset [<mode>] [<commit>]`::
- This form resets the current branch head to _<commit>_ and
@@ Documentation/git-reset.adoc: However, when you specify files or directories or
linkgit:git-add[1]).
+`--soft`::
-+ Leaves your working directory unchanged. The index is left unchanged,
-+ so everything in your current commit will be staged.
++ Leave your working tree files and the index unchanged.
+ For example, if you have no staged changes, you can use
+ `git reset --soft HEAD~5; git commit`
-+ to combine the last 5 commits into 1 commit.
++ to combine the last 5 commits into 1 commit. This works even with
++ changes in the working tree, which are left untouched, but such usage
++ can lead to confusion.
+
`--hard`::
- Resets the index and working tree. Any changes to tracked files in the
- working tree since _<commit>_ are discarded. Any untracked files or
- directories in the way of writing any tracked files are simply deleted.
+ Overwrites all files and directories with the version from _<commit>_,
-+ and may overwrite untracked files.
++ and may overwrite untracked files. Tracked files not in _<commit>_ are
++ removed so that the working tree matches _<commit>_.
+ Updates the index to match the new HEAD, so nothing will be staged.
`--merge`::
-+ Mainly exists for backwards compatibility: `git merge --abort` is the
-+ usual way to abort a merge. See linkgit:git-merge[1] for the differences.
++ Mainly exists to reset unmerged index entries, like those left behind by
++ `git am -3` or `git switch -m` in certain situations.
Resets the index and updates the files in the working tree that are
different between _<commit>_ and `HEAD`, but keeps those which are
different between the index and working tree (i.e. which have changes
4: 0b9583f872 ! 4: d6582dc53c doc: git-reset: clarify `git reset <pathspec>`
@@ Metadata
## Commit message ##
doc: git-reset: clarify `git reset <pathspec>`
- >From user feedback:
+ From user feedback:
- Continued confusion about the terms "tree-ish" and "pathspec"
- The word "hunks" is confusing folks, use "changes" instead.
@@ Documentation/git-reset.adoc: linkgit:git-add[1]).
-and specifying a commit with `--source`, you
-can copy the contents of a path out of a commit to the index and to the
-working tree in one go.
-+`git reset` only modifies the index: use linkgit:git-restore[1] instead
-+if you'd like to also update the file in your working directory.
++In this mode, `git reset` updates only the index (without updating the HEAD or
++working tree files). If you want to update the files as well as the index
++entries, use linkgit:git-restore[1].
`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
- Interactively select hunks in the difference between the index
@@ Documentation/git-reset.adoc: linkgit:git-add[1]).
- in reverse to the index.
+ Interactively select changes from the difference between the index
+ and the specified commit or tree (which defaults to `HEAD`).
-+ The chosen changes are unstaged.
++ The chosen changes are added to the index.
+
This means that `git reset -p` is the opposite of `git add -p`, i.e.
-you can use it to selectively reset hunks. See the "Interactive Mode"D. Ben Knoble <ben.knoble+github@gmail.com>