Skip to content

doc: git-reset: clarify DESCRIPTION section #1991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

doc: git-reset: clarify DESCRIPTION section #1991

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c7e1c09
doc: git-reset: reorder the forms
jvns Sep 12, 2025
6b5459b
doc: git-reset: clarify intro
jvns Sep 12, 2025
597ea0f
doc: git-reset: clarify `git reset [mode]`
jvns Sep 12, 2025
0be1664
doc: git-reset: clarify `git reset <pathspec>`
jvns Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions Documentation/git-reset.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
SYNOPSIS
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
> index 3b9ba9aee9..9843682e81 100644
> --- a/Documentation/git-reset.adoc
> +++ b/Documentation/git-reset.adoc
> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
>  SYNOPSIS
>  --------
>  [synopsis]
> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>  git reset [-q] [<tree-ish>] [--] <pathspec>...
>  git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
>  git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>  
>  DESCRIPTION
>  -----------
> -In the first three forms, copy entries from _<tree-ish>_ to the index.
> -In the last form, set the current branch head (`HEAD`) to _<commit>_,
> +In the first form, set the current branch head (`HEAD`) to _<commit>_,
>  optionally modifying index and working tree to match.
>  The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.

In the original, the "defaults to HEAD in all forms" did make sense,
but as the new text does not mention there are three other forms
like the original did, that sentence was made harder to fathom.
I can accept that you do not want to get ahead of yourself to
explain "copy from <treeish>" before you are ready to talk more
about these other forms, but we'd at least need to acknowledge that
what we want to refer to when we say "all forms" here.  Perhaps

    Among the four forms, the first form sets the current branch
    head to ....  In all forms, the tree-ish/commit defaults to
    HEAD.

is easier to read?

> +In the last three forms, copy entries from _<tree-ish>_ to the index.

Or "The other three forms copy entries ..."?

Other than that, looks good to me.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

On Fri, Oct 17, 2025, at 6:20 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email protected]> writes:
>
>> diff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc
>> index 3b9ba9aee9..9843682e81 100644
>> --- a/Documentation/git-reset.adoc
>> +++ b/Documentation/git-reset.adoc
>> @@ -8,43 +8,17 @@ git-reset - Reset current HEAD to the specified state
>>  SYNOPSIS
>>  --------
>>  [synopsis]
>> +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>>  git reset [-q] [<tree-ish>] [--] <pathspec>...
>>  git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
>>  git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
>> -git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
>>  
>>  DESCRIPTION
>>  -----------
>> -In the first three forms, copy entries from _<tree-ish>_ to the index.
>> -In the last form, set the current branch head (`HEAD`) to _<commit>_,
>> +In the first form, set the current branch head (`HEAD`) to _<commit>_,
>>  optionally modifying index and working tree to match.
>>  The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
>
> In the original, the "defaults to HEAD in all forms" did make sense,
> but as the new text does not mention there are three other forms
> like the original did, that sentence was made harder to fathom.

That's true. I didn't pay very careful attention to the text here
because I completely rewrote it in a later patch anyway.
I'll make it say something that makes more sense.

> I can accept that you do not want to get ahead of yourself to
> explain "copy from <treeish>" before you are ready to talk more
> about these other forms, but we'd at least need to acknowledge that
> what we want to refer to when we say "all forms" here.  Perhaps
>
>     Among the four forms, the first form sets the current branch
>     head to ....  In all forms, the tree-ish/commit defaults to
>     HEAD.
>
> is easier to read?
>
>> +In the last three forms, copy entries from _<tree-ish>_ to the index.
>
> Or "The other three forms copy entries ..."?
>
> Other than that, looks good to me.

--------
[synopsis]
git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
git reset [-q] [<tree-ish>] [--] <pathspec>...
git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]

DESCRIPTION
-----------
In the first three forms, copy entries from _<tree-ish>_ to the index.
In the last form, set the current branch head (`HEAD`) to _<commit>_,
In the first form, set the current branch head (`HEAD`) to _<commit>_,
optionally modifying index and working tree to match.
The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.

`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
These forms reset the index entries for all paths that match the
_<pathspec>_ to their state at _<tree-ish>_. (It does not affect
the working tree or the current branch.)
+
This means that `git reset <pathspec>` is the opposite of `git add
<pathspec>`. This command is equivalent to
`git restore [--source=<tree-ish>] --staged <pathspec>...`.
+
After running `git reset <pathspec>` to update the index entry, you can
use linkgit:git-restore[1] to check the contents out of the index to
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>...]`::
Interactively select hunks in the difference between the index
and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
in reverse 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"
section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
In the last three forms, copy entries from _<tree-ish>_ to the index.

`git reset [<mode>] [<commit>]`::
This form resets the current branch head to _<commit>_ and
Expand Down Expand Up @@ -98,6 +72,32 @@ but carries forward unmerged index entries.
the submodules' `HEAD` to be detached at that commit.
--

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> +`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.

I cannot judge if it is clear enough with the above sentence that we
are only talking about "the other forms", but if that is the case
and it is clear we are not talking about the mode where the command
repoints HEAD to another commit, the above is a good piece of advice.

If not, perhaps

    When specified what paths to modify, `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
    git-restore.

may be a way to clarify the distinction between two modes.

>  `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
> -	Interactively select hunks in the difference between the index
> -	and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
> -	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.
>  +
>  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"
> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
> +you can use it to selectively unstage changes. See the "Interactive Mode"
> +section of linkgit:git-add[1] to learn how to use the `--patch` option.

I do not see a good reason why we avoid saying the noun "patch",
especially when we see it in the option.  If we were allowed to say
"patch" here, "changes from the difference between ..." can be
rephrased to "parts of the patch that makes the index match the
specified commit", which may be simpler.

Also "unstaged" is only true when <tree-ish> is "HEAD".  If you are
grabbing the contents recorded in a different commit and shoving
them into the index, that is not "unstaging" at all.  Rather, if you
are planning to make a commit out of the index after doing so, that
is rather "staging" a change!  While the verb "to (un)stage" may
have been a useful tool to explain the act of updating index entries
to describe its effect relative to what is in HEAD, in this
particular case, it is probably more confusing than illuninating to
use it.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Ben Knoble wrote (reply to this):

> Le 17 oct. 2025 à 19:25, Junio C Hamano <[email protected]> a écrit :
> 
> "Julia Evans via GitGitGadget" <[email protected]> writes:
> 
>> `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
>> -    Interactively select hunks in the difference between the index
>> -    and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
>> -    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.
>> +
>> 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"
>> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
>> +you can use it to selectively unstage changes. See the "Interactive Mode"
>> +section of linkgit:git-add[1] to learn how to use the `--patch` option.
> 
> I do not see a good reason why we avoid saying the noun "patch",
> especially when we see it in the option.  If we were allowed to say
> "patch" here, "changes from the difference between ..." can be
> rephrased to "parts of the patch that makes the index match the
> specified commit", which may be simpler.

I think the issue was the word « hunk », not « patch ».

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Ben Knoble <[email protected]> writes:

>> Le 17 oct. 2025 à 19:25, Junio C Hamano <[email protected]> a écrit :
>> 
>> "Julia Evans via GitGitGadget" <[email protected]> writes:
>> 
>>> `git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
>>> -    Interactively select hunks in the difference between the index
>>> -    and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
>>> -    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.
>>> +
>>> 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"
>>> -section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
>>> +you can use it to selectively unstage changes. See the "Interactive Mode"
>>> +section of linkgit:git-add[1] to learn how to use the `--patch` option.
>> 
>> I do not see a good reason why we avoid saying the noun "patch",
>> especially when we see it in the option.  If we were allowed to say
>> "patch" here, "changes from the difference between ..." can be
>> rephrased to "parts of the patch that makes the index match the
>> specified commit", which may be simpler.
>
> I think the issue was the word « hunk », not « patch ».

I know.  That is exactly where my question comes from.

`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
These forms reset the index entries for all paths that match the
_<pathspec>_ to their state at _<tree-ish>_. (It does not affect
the working tree or the current branch.)
+
This means that `git reset <pathspec>` is the opposite of `git add
<pathspec>`. This command is equivalent to
`git restore [--source=<tree-ish>] --staged <pathspec>...`.
+
After running `git reset <pathspec>` to update the index entry, you can
use linkgit:git-restore[1] to check the contents out of the index to
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>...]`::
Interactively select hunks in the difference between the index
and _<tree-ish>_ (defaults to `HEAD`). The chosen hunks are applied
in reverse 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"
section of linkgit:git-add[1] to learn how to operate the `--patch` mode.

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

Expand Down