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 16, 2025, 20:48 UTC
Message-ID: <xmqqldmem8ds.fsf@gitster.g>
In-Reply-To: <de49d686-73fa-4bb9-9ec6-b65d5432a30a@anselmschueler.com>

Anselm Schüler <mail@anselmschueler.com> writes:

Show 7 quoted lines

> $ git status
> [...]
> No commits yet
>
> Changes to be committed:
>    (use "git rm --cached <file>..." to unstage)
> [...]

As this is a very initial commit, any file you are including would only exist in the index and in the working tree files. The index is where you prepare the contents of the commit you are going to create, and "git rm --cached <file>" is the way to remove <file> from there without losing or clobbering the <file> in the working tree. As you do not have a commit yet, you wouldn't have anywhere to "restore" from, would you?

Show 7 quoted lines

> After a commit has been made, git-status suggests using git-restore instead:
>
> $ git status
> [...]
> Changes to be committed:
>    (use "git restore --staged <file>..." to unstage)
> [...]

Compared to the previous situation, you do have a commit, so you can restore to the version in that commit. During the course of development that led you to this state, you may have added <file> in a commit way before the current commit, and you may have made changes to the <file> multiple times in different commits before the current commit. "git rm --cached <file>" would not be how you would go back to the version in the current commit in such a situation, as it would take you to the state _before_ you originally added that file. You would "restore" the contents in the index to that of the current commit (i.e. HEAD) to go back to the state.

So, isn't a short answer to the "why" question, "because that is what you need to do", I guess?