Git RM

The git rm command is used to remove specific files or a group of files from a Git repository.

The main purpose of git rm is to remove tracked files from the Staging Index, but it can also be used to remove files from the Working Directory.

There is no option for git rm to remove a file from just the Working Directory.

The git rm command does not remove branches.

Git uses a safety mechanism to block the removal of in-progress changes when the files are operated in are not identical to the files in the current HEAD.

Common Usage and Options

The git rm has several options. The following list shows different use cases:

• < file-name>... : It specifies the target files to remove by simply providing the file-name/ path to a single file. The option value can also be multiple file-names delimited by spaces (file1 file2 file3), or even a wildcard pattern (e.g. *.text)

  $ git rm <file-name>
  

• -f or --force: It is used to override the security check that Git makes to ensure that files in HEAD correspond to the content of the Staging Index and the Working Directory.

  $ git rm -f <file-name>
  

• -n or --dry-run: It's an option to simulate the execution of git rm, using -n options files will not be removed. Instead, it will output which files will be removed if the effective git rm is invoked.

  $ git rm -n *.html
  

• -r: It is a shorthand for 'recursive'. When working in recursive mode, the git rm removes the target directory and its whole content.

  $ git rm -r  folder-name
  

• --cached: It specified that the deletion should only happen on the Staging Index. The Working Directory files are untouched.

  $ git rm -n --cached filename
  rm 'file_name'
  

• --: It is used to make a distinction between a list of file names and the arguments being passed to git rm.

  $ git rm -n --cached -- file-1 file-2 file-3
  rm 'file_1'
  rm 'file_2'
  

• --ignore-unmatch: It exists with a 0 status even if no files matched. The code 0 is a Unix level status code that indicates a successful innovation of the command. The --ignore-unmatch can be useful when using git rm as part of a shell script.

  $ git rm --ignore-unmatch file-name
  

• -q or --quiet: It hides the output of the git rm command. The git rm command normally displays one line for each removed file.

  $ git rm -q -n file-name
  

How to undo git rm

Running git rm is not a permanent update. The git rm command updates the Working Directory and the Staging Index. These changes are not persisted until a new commit is created and the modifications are added to the Commit History, which means that they can be undone with git commands.

• git reset: A reset will revert the Working Directory and the Staging Index to the state of the HEAD commit. It will undo the git rm command.

  $ git reset HEAD
  

• checkout: A checkout will also restore the latest version of a file from HEAD.

  $ git checkout .
  

• In the case of a git rm was already executed, and a new commit was created, which persists the removal in the Commit History. The git reflog command can be used to search a ref located before the git rm execution. See more about git reflog

The scope of git rm

When the git rm command is executed, it affects only the current branch. The files that are concerned are files in the Working Directory and the Staging Index. The file deletion is not persisted to the Commit History until a new commit is created.

Using git rm instead of rm

A Git repository will know when a normal shell rm command has been executed on a file that Git is tracking. It will update the Working Directory to signal the removal, but it will not update the Staging Index. An extra git add command on the removed file should be executed to add the modifications to the Staging Index.

The git rm command acts like a shortcut to shell rm and git add. The git rm will update the Working Directory and the Staging Index with the removal.

Examples

Let us look at the following examples:

$ git rm directory_example/\*.txt

In the example above, we use a wildcard file glob to delete all *.txt files children of the 'directory_example' folder. We used slashes before asterisk to prevent the shell from expanding the wildcard.

$ git rm -f index_*.html

Here we used the force option and a wildcard for targeting index_*.html files. The force option is used to delete all the target files from the Working Directory and the Staging Index.

How to remove files no longer exist in the filesystem

The git rm is like a shortcut that combines the standard shell rm and git add to remove a file from the Working Directory and promote the removal to the Staging Index.

Sometimes a repository can be in a situation where several files have been removed using only the standard shell rm command. And you want to record all the removed files to be part of the next commit, execute the git commit -a command to add all the removal events to the Staging Index in preparation for the next commit.

However, if you want to remove all the files that were removed with the shell rm, use the following command:

$ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached

The command above will produce a list of all the removed files from the Working Directory and pipe this list to the git rm --cached command to update the Staging Index.