git-rm

Remove file from repository index and filesystem

$ git rm [path/to/file]

$ git rm -r [path/to/directory]

$ git rm --cached [path/to/file]

git rm [--cached] [-r | --recursive] [-f | --force] [-n | --dry-run] [--ignore-unmatch] <pathspec>...

--cached
    Only remove from the index. The file remains in the working tree. This is useful for untracking files that are mistakenly added to the repository.

-r, --recursive
    Allow recursive removal of directories. This option is mandatory when removing a directory.

-f, --force
    Override the up-to-date check. Use this option to force removal of a file that has different content in the working tree than in the index or has uncommitted changes.

-n, --dry-run
    Don't actually remove any file(s). Instead, just show what would be removed. This is useful for testing the command's effect before committing changes.

--ignore-unmatch
    Exit with a zero status even if no files match the provided <pathspec>. By default, git rm exits with a non-zero status if a pathspec does not match any files.

<pathspec>...
    The file(s) or directory(ies) to remove. Wildcards (e.g., *.txt) can be used, but require proper shell quoting to prevent shell expansion.

The git rm command removes files from the working tree and from the Git index (staging area). This command is used to record the removal of a file in your Git repository. Unlike the standard rm command, git rm not only deletes the file from your filesystem but also stages the deletion for the next commit. If a file has uncommitted changes (i.e., it's modified in the working tree and differs from the version in the index), git rm will refuse to remove it unless you explicitly use the --force option to prevent accidental data loss. This ensures that you don't inadvertently discard valuable work. The command can also be used to remove files only from the Git index, leaving them in the working tree, which is useful for untracking files without deleting them from your local disk.

git rm only affects files tracked by Git. It cannot remove untracked files; for those, use the filesystem rm command. Files removed with git rm are removed from the *current* state and will be absent in future commits, but they remain in the repository's history and can be recovered using commands like git log or git restore on previous commits. If you accidentally git rm a file before committing, you can typically recover it using git restore --staged <file> to undo the staging and git restore <file> to restore the working tree file.

The --cached option is crucial for untracking files that were accidentally committed or should no longer be tracked by Git (e.g., large data files, build artifacts). Using git rm --cached <file> removes the file from the Git index without deleting it from your local filesystem. After running this command, you typically add the file to your .gitignore file to prevent it from being re-added in subsequent git add . operations, thus effectively untracking it for all future commits.

git rm incorporates built-in safety mechanisms. By default, it will prevent you from removing a file that has uncommitted changes in your working tree (i.e., modifications not yet staged or committed) or if the file in the working tree differs from the version in the index. This prevents accidental loss of data. To override this safety, you must explicitly use the --force (or -f) option, indicating that you understand and accept the potential data loss and wish to proceed with the removal despite inconsistencies.

The git rm command has been a foundational part of Git since its inception. It was designed as a core utility to manage the lifecycle of files within a Git repository, specifically handling deletions. Its fundamental behavior of removing files from both the working directory and the index, coupled with safety checks against accidental data loss, has remained consistent throughout Git's development. The introduction of options like --cached further enhanced its utility, allowing for more granular control over tracking files, especially for managing repository size and accidental inclusions.

git add(1), git mv(1), git restore(1), git clean(1), rm(1)