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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 20, 2025, 20:44 UTC
Message-ID: <xmqqcy6hz4jh.fsf@gitster.g>
In-Reply-To: <a6d94c76-c9fe-4688-8eea-3bbab2b5dc07@app.fastmail.com>

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

Show 12 quoted lines

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

Show 5 quoted lines

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