Day 20/30 - Git rm --cached: Remove Files from Staging but Keep Locally

Introduction

When working with Git, you might accidentally stage files you didn't mean to include in your next commit. The git rm --cached command helps you remove files from the staging area while keeping them in your working directory.

What is `git rm --cached`?

The git rm --cached command removes files from Git's staging area (index) but keeps them in your local working directory. This is useful when:

You accidentally staged files you didn’t mean to (git add mistakes).
You want to untrack a file but keep it locally.
You need to remove files from version control without deleting them.

Basic Syntax

git rm --cached <file>

When to Use `git rm --cached` (With Examples)

Scenario 1: Accidentally Staged a File

You ran git add . and accidentally staged config.json, which contains sensitive data.

# Check staged files  
git status  

# Remove from staging but keep locally  
git rm --cached config.json  

# Verify it's now untracked but still exists  
git status  
ls

Result:

config.json is no longer staged.
It remains in your working directory.

Scenario 2: Stop Tracking a File but Keep It Locally

You added logs/debug.log to Git earlier, but now you want Git to ignore it (via .gitignore) while keeping the file.

# Step 1: Add logs/ to .gitignore  
echo "logs/" >> .gitignore  

# Step 2: Remove from Git but keep locally  
git rm --cached logs/debug.log  

# Step 3: Commit the change  
git add .gitignore  
git commit -m "Stop tracking logs directory"

Result:

debug.log is no longer tracked.
Future changes to logs/ won’t appear in git status.

Scenario 3: Removing a File from Git History (Advanced)

You committed a large binary file (dataset.zip) and want to completely remove it from Git history while keeping it locally.

# Step 1: Remove from staging & working directory (if needed)  
git rm --cached dataset.zip  

# Step 2: Commit the removal  
git commit -m "Remove dataset.zip from tracking"  

# Step 3: Optional: Rewrite Git history (for a clean slate)  
git filter-branch --tree-filter 'rm -f dataset.zip' HEAD

Result:

dataset.zip is no longer in Git history.
The file remains in your local folder.

Key Differences: `git rm --cached` vs `git rm` vs `git reset`

Command	Effect	Use Case
`git rm --cached <file>`	Removes from staging, keeps locally	Untrack files without deleting
`git rm <file>`	Removes from staging AND deletes locally	Delete files permanently
`git reset <file>`	Unstages changes but keeps tracking	Undo `git add` without untracking

Example:

# Case 1: Keep file but untrack it  
git rm --cached file.txt  

# Case 2: Delete file completely  
git rm file.txt  

# Case 3: Unstage changes but keep tracking  
git reset file.txt

Advanced Use Cases

1. Undo `git add .` Without Losing Work

Problem: You ran git add . and staged everything, including unwanted files.

Solution:

# Remove all staged files but keep them locally  
git rm --cached -r .  

# Now selectively re-add what you need  
git add src/

Combine with git restore --staged . for a safer unstaging.

2. Remove Files from Git History Without `filter-branch`

Problem: You committed a large file (e.g., data.db) and want to purge it from history without complex commands.

Solution:

git rm --cached data.db  
git commit -m "Remove data.db from tracking"  
git push origin main --force

⚠ Warning: Force-pushing rewrites history—use only in private repos or with team coordination!

3. Fix `git clone` With Partial Checkout

Problem: You cloned a huge repo but only need specific folders (e.g., docs/).

Solution:

git clone --no-checkout <repo-url>  
cd repo  
git rm --cached -r .  # Remove everything from staging  
git add docs/         # Only keep docs  
git commit -m "Keep only docs/"  
git checkout main

Result: Your working dir only has docs/—saves disk space!

4. Recover Deleted Files After `git rm`

Mistake: You ran git rm file.txt (without --cached) and deleted the file.

Fix:

# Restore from Git's index  
git checkout -- file.txt  

# If not in Git, recover from system trash or use:  
git fsck --lost-found

5. Remove Empty Directories After Untracking

Problem: git rm --cached dir/ leaves empty folders behind.

Solution:

find . -type d -empty -delete

6. Secretly Exclude Files Without `.gitignore`

Advanced Trick: Use --assume-unchanged to hide changes from Git.

git update-index --assume-unchanged secret.env

When to Use:

Temporary local overrides (e.g., debug flags).
Sensitive files you never want to accidentally commit.

7. Speed Up Big Repos with `--sparse-checkout` + `--cached`

For Giant Repos: Clone only what you need and ignore the rest.

git clone --filter=blob:none --sparse <repo-url>  
cd repo  
git sparse-checkout set src/  
git rm --cached -r .  # Remove everything  
git add src/           # Only track src/

Result: Faster clones, less disk usage!

Conclusion

git rm --cached is useful for untracking files without deleting them.
Always check git status before and after running the command.
For sensitive data removal, consider rewriting history (git filter-branch or BFG Repo-Cleaner).

By mastering git rm --cached, you can better manage your Git workflow—whether you're a beginner fixing mistakes or a pro optimizing repository size.

Up Next in the Series: git update-ref – Manually update branch references

Daily advance GIT tips in your inbox---worth starting? Respond to my poll here🚀

For more useful and innovative tips and tricks, Let's connect on Medium

Ruqaiya Beguwala @ruqaiya_beguwala