Synopsis
git rm [-f] [-r] [--cached] [--] <file>...Description
The git rm command removes files from the working tree and the index in one step, staging the deletion for the next commit. Using git rm is more convenient than removing the file with rm and then running git add — although both approaches produce the same end state.
The --cached flag is particularly useful: it removes the file from the index without deleting it from the working tree. This is the right tool when you accidentally committed a file (such as a config file with secrets, or a build artifact) and want to stop tracking it but keep it on disk.
In day-to-day use, git rm integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git rm --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git rm interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git rm's side effects helps avoid all three.
Common Options
| Option | Description |
|---|---|
-f, --force | Override safety checks if the file has uncommitted changes. |
-r | Recursively remove directories. |
--cached | Remove from index only; leave the working tree file alone. |
-n, --dry-run | Show what would be removed without doing it. |
--ignore-unmatch | Exit zero even if no files match. |
-q, --quiet | Suppress output. |
Examples
git rm old-file.txt
# Delete the file and stage the deletion
git rm -r build/
# Recursively remove a directory from the repo
git rm --cached secrets.env
# Stop tracking a file but keep it locally
# Then add it to .gitignore!
git rm -n '*.log'
# Preview which log files would be removedCommon Mistakes
The biggest gotcha is forgetting that git rm --cached only stops future tracking — past commits still contain the file. If you need to purge a secret from history, use git filter-repo or BFG. Another mistake is running git rm on a file with unstaged modifications without realizing those changes are lost. Use -n first when in doubt.
Related Commands
git add, git mv, git restore, git filter-repo