How to unstage a file in Git

How to undo a Git add

To unstage a file in the Git index and undo a git add operation, any of the following three commands will work, although only the git restore command is recommended:

  1. git restore --staged file-to-unstage.txt
  2. git reset file-to-unstage.txt
  3. git rm --cached file-to-unstage.txt

There may be unintended consequences when you use git reset or git rm to  The git restore command is the best option.

Git unstage example

To unstage a file named file.html from Git’s staging index, enter this command in the terminal window:

git restore --staged file-to-unstage.txt

Here’s a quick, real-world example of how to remove a file from the Git index. In this example we perform the following tasks:

  • Clone a sample Git repo.
  • Create a new file with the touch command.
  • Add the file to the Git index.
  • Unstage the file with git restore.

Devs use the git status command to monitor the state of the file.

$ git clone
Remote repository successfully cloned

$ cd ufe
Switched to /ufe directory

$ touch file.html
File named file.html created

$ git status
Untracked files: file.html

$ git add file.html
$ git status
Changes to be committed: new file: file.html

$ git restore --staged file.html
Git file unstaged successfully

$ git status
Untracked files: file.html

Restore and rm to unstage Git index files

The git restore command was introduced in 2019 as part of Git version 2.23.

Prior to the git restore command, people commonly used git reset to unstage Git files, like so:

git reset file-to-unstage.txt

This command still works, but it is not the recommended approach.

The reset command is powerful, and is able to rewrite your branch history. To avoid any unintended consequences with an incorrectly issued instruction, it’s best to avoid reset and stick with restore to untrack a Git file.

Don’t unstage Git files from the index with rm

Another option often cited to remove a file from the Git index is the rm command:

git rm --cached file.txt

However, you should avoid his option, because this may not only remove the file from the index, but remove it from the repo altogether.

When others pull after you have pushed, the file may not appear in their repositories at all.

The bottom line? If you want to unstage a file in Git, use the restore command. That’s what it’s there for.

App Architecture
Software Quality
Cloud Computing