In Git, what does git rm --cached do, and when do you need it?

## What the flag actually changes `git rm` normally does two things at once: it removes the path's entry from the index and it unlinks the file from the working tree. `--cached` keeps the first half and skips the second. Placed on the three-trees diagram, it is an index-only operation — HEAD still has the file, the working tree still has the file, and the index no longer does. `git status` therefore shows a staged deletion, and once you commit, the working-tree copy becomes an untracked file. Safety behaviour is worth knowing: `git rm` refuses to proceed when the working-tree copy differs from what is recorded, so you cannot lose unsaved content by accident, and `-f` overrides that check. `-r` is required to recurse into a directory, and `--ignore-unmatch` makes the command exit zero when the path matches nothing, which is handy inside scripts. ## The canonical use case Someone commits a file that never belonged in the repository. The fix is a single small change containing three things: an ignore rule for the path, `git rm --cached` on it, and a commit that carries both. Do the ignore rule too late and the file simply reappears as untracked noise for everyone; do the removal without the ignore rule and the next careless `git add -A` re-adds it. The recursive variant `git rm -r --cached .` untracks *everything* without touching the disk. Following it with `git add .` re-adds only what current ignore rules permit, which is the standard way to make a newly written or corrected ignore file take effect on already-tracked paths. It produces one large mechanical commit, so it is worth doing on its own rather than mixed into feature work. ## The two things it does not do **It does not spare your colleagues.** The commit records a deletion of that path. When they pull, Git applies that deletion to their working tree, and the file disappears from their machine even though it survived on yours. If the file held per-developer configuration, tell the team before landing it, and ship a checked-in template file alongside the ignore rule so people can recreate their local copy. **It does not remove anything from history.** Git stores snapshots; every commit that contained the file still contains it, and the blob remains reachable through those commits, so garbage collection will never drop it. A credential that was pushed is compromised the moment it was pushed. Rotate the credential first; deciding whether to rewrite history is a separate, much heavier conversation. ## Neighbouring index-only operations `git mv old new` is the mirror image: it renames the file on disk and updates the index in one step, equivalent to `mv` followed by `git rm` on the old path and `git add` on the new one. Git does not store renames — a commit is a snapshot, so a rename is simply one path gone and another arrived. What `git mv` buys you is that the index is updated for you; the arrow you later see in `git status` or `git log --follow` comes from diff-time similarity detection, not from anything the command recorded. A related distinction candidates blur: untracking with `git rm --cached` is a real, shareable change to the repository's contents, while marking a file with `git update-index --assume-unchanged` or `--skip-worktree` is a purely local index flag that keeps the file tracked. If the file should not be in the repository, untrack it.