Introduction

Removing a directory from a Git repository has two distinct meanings: removing it from tracking (so Git stops versioning it) while keeping it on your local filesystem, or removing it from both Git and your disk. The git rm -r --cached command handles the first case, and git rm -r handles the second. Understanding the difference prevents accidental data loss.

Remove from Git Only (Keep Local Files)

1# Stop tracking the directory but keep it on disk
2git rm -r --cached my-directory/
3
4# Commit the removal
5git commit -m "Remove my-directory from version control"
6
7# Push to remote
8git push origin main

After this, my-directory/ still exists on your local machine but Git no longer tracks it. Other collaborators who pull this change will have the directory deleted from their working copy.

The --cached flag tells Git to remove the files from the staging area (index) only, not from the working tree.

Remove from Git AND Local Disk

1# Delete the directory from both Git and your filesystem
2git rm -r my-directory/
3
4# Commit
5git commit -m "Delete my-directory"
6
7# Push
8git push origin main

Without --cached, git rm -r deletes the files from your disk AND removes them from Git tracking.

Adding to .gitignore After Removal

If you removed a directory from tracking but want to prevent it from being re-added:

1# 1. Remove from tracking
2git rm -r --cached my-directory/
3
4# 2. Add to .gitignore
5echo "my-directory/" >> .gitignore
6
7# 3. Commit both changes
8git add .gitignore
9git commit -m "Remove my-directory from tracking and add to .gitignore"

The order matters. .gitignore only affects untracked files. If the directory is still tracked, .gitignore has no effect. Remove it from tracking first, then add the ignore rule.

Common Use Cases

Remove build artifacts

1git rm -r --cached build/
2git rm -r --cached dist/
3git rm -r --cached node_modules/
4echo "build/" >> .gitignore
5echo "dist/" >> .gitignore
6echo "node_modules/" >> .gitignore
7git add .gitignore
8git commit -m "Remove build artifacts from tracking"

Remove IDE configuration

1git rm -r --cached .idea/
2git rm -r --cached .vscode/
3echo ".idea/" >> .gitignore
4echo ".vscode/" >> .gitignore
5git add .gitignore
6git commit -m "Remove IDE config from tracking"

Remove accidentally committed secrets

1git rm -r --cached config/secrets/
2echo "config/secrets/" >> .gitignore
3git add .gitignore
4git commit -m "Remove secrets directory from tracking"

Note: This removes the directory from the current commit, but it still exists in Git history. To purge it from all history, you need git filter-branch or BFG Repo-Cleaner.

Removing from All Git History

If the directory contains sensitive data (API keys, passwords), removing it from the latest commit is not enough because it still exists in previous commits:

1# Using git filter-branch (built-in, slower)
2git filter-branch --force --index-filter \
3  'git rm -r --cached --ignore-unmatch secrets/' \
4  --prune-empty --tag-name-filter cat -- --all
5
6# Force push (destructive, coordinate with team)
7git push origin --force --all

1# Using BFG Repo-Cleaner (faster, easier)
2# Download bfg.jar from https://rtyley.github.io/bfg-repo-cleaner/
3
4# Remove directory from all history
5java -jar bfg.jar --delete-folders secrets
6
7# Clean up
8git reflog expire --expire=now --all
9git gc --prune=now --aggressive
10git push --force

Preview Before Removing

1# Dry run: see what would be removed without doing it
2git rm -r --cached --dry-run my-directory/
3# rm 'my-directory/file1.txt'
4# rm 'my-directory/file2.txt'
5# rm 'my-directory/subdir/file3.txt'

The --dry-run flag shows exactly which files would be affected.

Removing a Single File

1# Remove from Git only
2git rm --cached path/to/file.txt
3
4# Remove from Git and disk
5git rm path/to/file.txt

Same flags as directory removal, just without -r.

Checking What Git Tracks

1# List all tracked files in a directory
2git ls-files my-directory/
3
4# Check if a file is tracked
5git ls-files --error-unmatch path/to/file.txt
6# Exit code 0 = tracked, 1 = not tracked

Common Pitfalls

• Forgetting --cached: Running git rm -r my-directory/ without --cached deletes files from your disk. Use --cached when you want to keep local files.
• Not adding to .gitignore: After git rm --cached, the untracked directory will show in git status. If someone runs git add ., it gets re-added. Always update .gitignore.
• Thinking .gitignore removes tracked files: .gitignore only prevents adding new untracked files. It does not remove already-tracked files. You must git rm --cached first.
• Force pushing after history rewrite: git filter-branch and BFG rewrite commit hashes. All collaborators must re-clone or rebase. Coordinate with your team before force pushing.
• Large directories in history: Removing node_modules/ from the current commit reduces the repo's working tree but not its .git directory size. The old data persists in history until you rewrite history and run git gc.

Summary

• git rm -r --cached dir/ removes from Git tracking but keeps local files
• git rm -r dir/ removes from both Git and your local filesystem
• Always add the directory to .gitignore after removing from tracking to prevent re-addition
• Use --dry-run to preview what would be removed
• For sensitive data in history, use BFG Repo-Cleaner or git filter-branch to purge from all commits
• .gitignore only affects untracked files. It cannot remove already-tracked directories