Re: Why does git-status suggest different commands to unstage files depending on whether there is a commit yet or not?

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 17, 2025, 12:12 UTC
Message-ID: <xmqqqzw5i8fv.fsf@gitster.g>
In-Reply-To: <CALnO6CCz6dFX1Est0hhCbvaepBvG4+rpYQRQ2bP5vAQVmaY=OA@mail.gmail.com>

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

Show 12 quoted lines

> ... " the following
> does work in a non-unborn repo to move "newfile" from "untracked" to
> "staged" and back again:
>
>     echo >newfile && git add newfile
>     git restore --staged newfile
>
> So we don't need "rm --cached" to
>
>> remove <file>
>> from there [the index] without losing or clobbering the <file> in the working
>> tree

Now I think about it more, I wonder if "restore --staged" is misleading and confusing to new users?

When you teach "git restore" what would you tell them?

NAME
       git-restore - Restore working tree files

is how "git restore --help" starts. It is primarily a tool to let you repair messed up files in your working tree by copying out of a known good version from somewhere, be it from the index or from an existing commit.

But the instruction used to recover from unwanted "git add" to update the index with modified contents does NOT want to destroy your files in the working tree. You want to repair only the index without touching your working tree files, because you added modified contents that were not ready to be "staged". Hence "git restore" is used with "--staged" option to tell it to do what it was *not* primarily designed to do, i.e. only touch the index without doing its usual "Restore working tree files" job.

But there is a lot more appropriate command whose primary focus is about the index. "git reset <file>" would grab the contents for the <file> in HEAD and replace the index entry for <file> with it, which is exactly how you would move the "Changes to be committed" files to "Changes not staged for commit" status.

So I think use of "git restore --staged" in the instruction is wrong, and it should be replaced with "git reset" instead.

> (But the point about having nowhere to restore from stands!)

Yes, and the point about having nowhere to reset from stands for the state on an unborn branch. That one needs "rm --cached".