Stop tracking a file but keep it locally: git rm --cached

git rm --cached FILE removes FILE from Git's index, so the next commit deletes it from the repository, but leaves the file on your disk. Combine it with a .gitignore entry so it is not added again. .gitignore alone does nothing for files that are already tracked: it only affects untracked files.

Example

A log file was committed by mistake:

git init -q repo && cd repo
printf 'print("hi")\n' > app.py
printf 'debug output\n' > debug.log
git add . && git commit -q -m "initial"
echo "debug.log" > .gitignore
printf 'more output\n' >> debug.log
echo "--- .gitignore alone: still tracked"
git status --short
git rm -q --cached debug.log
git add .gitignore
git commit -q -m "Stop tracking debug.log"
echo "--- tracked files"
git ls-files
echo "--- still on disk"
ls
git status --short --ignored

--- .gitignore alone: still tracked
 M debug.log
?? .gitignore
--- tracked files
.gitignore
app.py
--- still on disk
app.py
debug.log
!! debug.log

!! debug.log in git status --ignored confirms the file is now ignored, and it is still in the working directory.

Errors you may see

Directories need -r. Without it Git refuses:

git init -q repo && cd repo
mkdir build && echo x > build/out.bin
git add . && git commit -q -m "initial"
git rm --cached build

fatal: not removing 'build' recursively without -r

A name that is not tracked fails with pathspec did not match any files; check the exact path with git ls-files. When the index holds a version that differs from both the last commit and the file on disk, Git stops with error: the following file has staged content different from both the file and the HEAD and suggests -f; with --cached -f, only that staged version is discarded and the file on disk is kept.

Directories and patterns

git rm -r --cached node_modules        # a whole directory
git rm --cached '*.log'                # quoted so Git expands the pattern, not the shell
git rm -r --cached . && git add .      # re-apply .gitignore to everything (review the diff before committing)

To keep a tracked file in the repository but ignore your local changes to it, git rm --cached is the wrong tool; git update-index --skip-worktree FILE does that for one clone.

Variants

If you only staged a file by mistake and never committed it, git restore --staged is the simpler command.

FAQ