Re: [PATCH 3/4] doc: git-reset: clarify `git reset [mode]`

From: Julia Evans <julia@jvns.ca>
Date: Oct 20, 2025, 20:23 UTC
Message-ID: <a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com>
In-Reply-To: <xmqqy0p8x12c.fsf@gitster.g>

On Sat, Oct 18, 2025, at 12:53 AM, Junio C Hamano wrote:

Show 6 quoted lines

> "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.

Show 8 quoted lines

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

Show 7 quoted lines

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

Show 11 quoted lines

>>  `--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)

Show 8 quoted lines

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

Show 13 quoted lines

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