From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`
Date: Mon, 20 Oct 2025 16:23:44 -0400 [thread overview]
Message-ID: <a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com> (raw)
In-Reply-To: <xmqqy0p8x12c.fsf@gitster.g>
On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com> writes:
>
>> +`--soft`::
>> + Leaves your working directory unchanged. The index is left unchanged,
>
> Why not "leave your working tree files and the index unchanged"?
The reason I say "working directory" instead of "working tree" is that
I've seen a few comments from users saying that they don't know
what "working tree" means. I'm still not sure what the reason for
calling it a "working tree" is.
The reason for keeping them separate sentences is just for symmetry with
the other commands, and also because (like I mentioned in the commit
message) "leaving X and Y unchanged" makes it sound like leaving X and
Y unchanged is a "neutral operation", while actually leaving the index
unchanged while updating HEAD is actually a fairly weird thing to do.
>> + so everything in your current commit will be staged.
>
> Hmph, if a reader still has the "stage the changes" mental model,
> then this would be true only when you are resetting to HEAD~1 (this
> is one of the reasons why I am hesitant to overuse the verb
> "stage"). If you are going to HEAD~5, such a reader would say that
> the changes made by the past 5 commits are staged, not just the
> commit you are on before resetting.
That's fair. I'll try to think about whether there's a better way to say
this.
Previously it said "This leaves all your changed files
"Changes to be committed", as git status would put it.", which has the
same issue ("changed files" since when exactly?).
Maybe I can fix this by being more explicit about which changes
exactly will show up as "staged" in `git status`.
>> + 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.
>
> Another thing that may be worth mentioning is that you can do this
> even with local changes in the working tree, because you do not give
> "-a" to the final "git commit".
Maybe! I'm not sure if we want to encourage doing complex Git operations
with unstaged changes though. I feel like it often leads to suffering
and I think people who want to do that can already infer that it's
possible.
>> `--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.
>> + Updates the index to match the new HEAD, so nothing will be staged.
>
> One thing that may be worth saying is that the paths in the working
> tree that are tracked in the index that are not in <commit> will
> disappear.
Interesting, I don't think I knew that. Would this be a more accurate
description of what `git reset --hard` does, conceptually?
I want to make sure I understand how it works.
1. List every file that's either in the target commit or in the index
2. For each file, make it match the target commit
(overwriting untracked files if necessary)
>> `--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.
>
> There are operations that are not "git merge" that can leave the
> index in an unmerged state, and you do not want to use "git merge
> --abort" to get out of such a state, I would imagine. So I have a
> feeling that we are better off without these two lines.
Do you mean `git reset` and `git cherry-pick`, or are there other operations
that can leave the operation in an unmerged state?
My mental model is that if there's a merge conflict, the best way to deal with it
is to use the appropriate `--abort` command (depending on how you got there),
because the command-specific `--abort` will know how to do things like
restore autostashed changes. But I agree that just saying "use `git merge --abort`
is not a complete description.
>> 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
>> which have not been added).
>> If a file that is different between _<commit>_ and the index has
>> unstaged changes, reset is aborted.
>> -+
>> -In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
>> -but carries forward unmerged index entries.
>
> I do not mind losing this. Unlike the time back when these two
> lines were written, nobody knows (and more importantly, nobody has
> to know) what "read-tree -u -m" does, these days.
Thanks, it's useful for me to know more about the context at the time
this was written.
next prev parent reply other threads:[~2025-10-20 20:24 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-17 20:05 [PATCH 0/4] doc: git-reset: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-17 20:05 ` [PATCH 1/4] doc: git-reset: reorder the forms Julia Evans via GitGitGadget
2025-10-17 22:20 ` Junio C Hamano
2025-10-20 19:03 ` Julia Evans
2025-10-17 20:05 ` [PATCH 2/4] doc: git-reset: clarify intro Julia Evans via GitGitGadget
2025-10-17 22:32 ` Junio C Hamano
2025-10-20 19:29 ` Julia Evans
2025-10-20 20:00 ` Junio C Hamano
2025-10-20 20:30 ` D. Ben Knoble
2025-12-03 18:15 ` Julia Evans
2025-10-17 20:05 ` [PATCH 3/4] doc: git-reset: clarify `git reset [mode]` Julia Evans via GitGitGadget
2025-10-18 4:53 ` Junio C Hamano
2025-10-20 20:23 ` Julia Evans [this message]
2025-10-20 20:33 ` D. Ben Knoble
2025-10-20 20:44 ` Junio C Hamano
2025-10-17 20:05 ` [PATCH 4/4] doc: git-reset: clarify `git reset <pathspec>` Julia Evans via GitGitGadget
2025-10-17 23:25 ` Junio C Hamano
2025-10-18 14:06 ` Ben Knoble
2025-10-18 16:17 ` Junio C Hamano
2025-12-19 0:23 ` [PATCH v2 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 2/4] doc: git-reset: clarify intro D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2025-12-19 0:23 ` [PATCH v2 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2025-12-30 5:23 ` Junio C Hamano
2026-01-01 22:32 ` D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-01 22:43 ` [PATCH v3 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-02 13:49 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-02 14:28 ` Jean-Noël AVILA
2026-01-01 22:43 ` [PATCH v3 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 1/4] doc: git-reset: reorder the forms D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 2/4] doc: git-reset: clarify intro D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 3/4] doc: git-reset: clarify `git reset [mode]` D. Ben Knoble
2026-01-05 21:48 ` [PATCH v4 4/4] doc: git-reset: clarify `git reset <pathspec>` D. Ben Knoble
2026-01-07 3:55 ` [PATCH v4 0/4] doc: git-reset: clarify DESCRIPTION section Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox