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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

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

"working tree" refers to the directory that is the top level of a
checkout; I'd view (current) "working directory" can be anything
$(pwd), that may be outside control of any git repository, and that
is why I tend to avoid the latter when I want to be more precise
(and "worktree" is another thing---used to refer to one particular
"working tree" among other working trees attached to the same
repository).

But that distinction was not the part I wanted to comment on.  The
question was about two sentences talking about two things
separately.  IOW

	Leave your working directory and the index unchanged.

is what I would have expected, and I was wondering why they are
treated separately.  After all, the index is part of your working
tree state.

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

Sorry, but I do not understand this comment.

The index and the HEAD are two different things, and it is natural
that they can move independently.  After all we update the former
without updating the latter all the time (it is called "git add").

Besides, the two things the --soft does not touch are the files in
the working tree and the index.  The index has what you want to make
the next commit out of, and the working tree has the state that may
come after that state in the index.  Keeping both of them intact
when moving HEAD around is one natural thing to do when you want to
squash the previous N commits after "git add <paths>" by doing "git
reset --soft HEAD~N && git commit".  Contrasting to that, "--mixed"
would leave the files in the working tree intact, while matching the
index to the HEAD you are moving to, essentially undoing your "git
add"s before you decided to reset.  That's another natural thing to
do when you decide to keep the clean slate and rebuild your index from
scratch to prepare for a commit that comes on top of the commit you
are moving to.

So, no, I do not understand the above comment.

> Do you mean `git reset` and `git cherry-pick`, or are there other operations
> that can leave the operation in an unmerged state?

There are many commands that leaves the index unmerged, like "am
-3", "rebase", "switch -m", "stash pop", etc.