Sometimes you need Git to stop tracking a file — like a config file with local settings or a large binary you accidentally added — without wiping it off your hard drive. The git rm --cached command does exactly that: it untracks the file while leaving the physical copy untouched.
Using git rm –cached
The core command for this task removes a file from Git’s index (the staging area) while keeping it in your working directory.
git rm --cached filename.txt
After running this, Git shows the file as untracked rather than deleted. Checking your file system confirms the file is still sitting right where you left it.
Removing Multiple Files or Entire Folders
You can untrack several files in a single command by listing them together.
git rm --cached file1.js file2.js file3.js
To untrack an entire directory and everything in it, add the recursive flag.
git rm -r --cached foldername
This removes every file inside the folder from tracking while leaving the folder and its contents on disk.
Handling Already-Staged Files
If you’ve already run git add on the file, you may need to unstage it first before removing it from tracking.
git reset HEAD filename.txt
git rm --cached filename.txt
Preventing the File From Being Re-Added
Untracking a file doesn’t stop it from being added again by accident. Adding it to .gitignore closes that gap for the future.
echo "filename.txt" >> .gitignore
git add .gitignore
Important: .gitignore only affects files Git isn’t already tracking. If a file is still tracked, adding it to .gitignore has no effect until you run git rm --cached on it first.
Committing the Change
None of this takes effect in the repository until you commit and, if needed, push.
git commit -m "Remove filename.txt from tracking"
git push
A Common Mistake to Avoid
Forgetting the --cached flag is the most frequent slip-up. Without it, git rm filename.txt deletes the file from both the Git repository and your local file system. If that happens before you’ve committed, you can usually recover it:
git checkout -- filename.txt
What This Doesn’t Do
git rm --cached only stops tracking a file going forward — it doesn’t erase the file from your commit history. If the file contains something sensitive, like an API key or password, it will still be recoverable from earlier commits. Removing it from history entirely requires rewriting history with tools like git filter-branch or git filter-repo, which is a more involved process and should be done with caution, especially on shared repositories.
Join The Discussion
Untracking files without deleting them is one of those Git tasks that trips up beginners and occasionally catches even experienced developers off guard. Have you ever run git rm without the --cached flag by mistake, or run into a situation where a “removed” file kept reappearing because of a .gitignore gotcha? Share your experiences, workflow tips, or questions below — what’s your go-to approach for keeping sensitive or local-only files out of your repo?
