Git rm Command Explained (Remove Files, Undo & --cached Examples)

What is git rm? (Quick Introduction)

The git rm command is used to remove files or directories from both the working directory and the Git repository. When you delete a file using git rm, Git tracks the removal and stages it for the next commit.

In simple terms, git rm helps you safely delete tracked files while keeping the change in version history. If you only want to stop tracking a file but keep it locally, you can use the --cached option.

git rm Cheat Sheet (Commands & Use Cases)

Common git rm Commands

Remove file using git rm

Use the git rm command to delete a tracked file from both the working directory and the Git repository. This is the safest way to remove files because Git records the deletion in version history.

git rm file.txt

Remove directory using git rm -r

To delete a folder and all its contents, use the recursive option -r. This ensures all tracked files inside the directory are removed properly.

git rm -r folder/

You can also explore more file operations in Git delete file or directory explained.

Remove forcefully using git rm -rf

If the file has local changes or is staged, Git may prevent deletion. In such cases, use the force option -f along with recursive deletion.

git rm -rf folder/

Use this carefully, especially when working with important branches. Learn safer workflows in Git workflow explained.

Untrack file using git rm --cached

Use --cached when you want to remove a file from Git tracking but keep it in your local system. This is commonly used for files added by mistake or sensitive files.

git rm --cached file.txt

For a deeper understanding, check Git remove file from tracking.

Real-World Scenarios

Delete a tracked file from Git

When a file is no longer needed in your project, use git rm to remove it cleanly. This ensures the deletion is tracked and shared with your team after commit.

git rm config.old
git commit -m "Remove unused config file"

Remove file but keep it locally (git rm --cached)

If you accidentally committed a file (like .env or logs), you can untrack it without deleting it locally.

git rm --cached .env
git commit -m "Stop tracking .env file"

Pair this with .gitignore for better control. See Gitignore examples.

Remove folder recursively (git rm -r)

When cleaning up project structure, you may need to delete entire directories.

git rm -r logs/
git commit -m "Remove logs directory"

Force delete ignored or modified files

Sometimes Git blocks deletion due to changes. Use -f to override safely when you are sure.

git rm -f file.txt

If you want to discard changes instead, refer to Git discard changes.

Remove files already pushed to remote

If a file is already pushed to a remote repository, removing it requires committing the deletion and pushing again.

git rm secret.txt
git commit -m "Remove sensitive file"
git push

If sensitive data was exposed, consider rewriting history using advanced methods in Git remove commit guide.

Undo git rm

Restore deleted file before commit

If you have used git rm but have not committed the changes yet, you can easily restore the file using the git restore command. This brings the file back from the staging area to your working directory.

git restore file.txt

This is the safest and quickest way to undo accidental deletions before committing changes.

Restore file after commit using git checkout

If the deletion is already committed, you can recover the file from a previous commit using git checkout.

git checkout HEAD~1 -- file.txt

This restores the file from the previous commit. You can also specify any commit hash if needed.

For more details on navigating commits, refer to Git HEAD, caret (^) and tilde (~) explained.

Undo git rm using git restore

In modern Git versions, git restore is the recommended way to undo file deletions or changes.

git restore --source=HEAD file.txt

This restores the file from the latest commit without affecting other changes.

You can explore more in Git restore command explained.

Recover deleted files using git reflog

If you are unsure where the file existed, use git reflog to view all recent changes and recover lost commits.

git reflog
git checkout <commit-id> -- file.txt

This is useful when files are deleted after multiple operations or resets.

Learn more in Git reflog tutorial.

git rm --cached Explained

What does git rm --cached do?

The git rm --cached command removes a file from Git tracking but keeps it in your local filesystem. It is commonly used when a file was mistakenly added to the repository.

git rm --cached file.txt

After running this command, the file becomes untracked but still exists locally.

When to use git rm --cached

Use git rm --cached in scenarios like:

• Removing sensitive files (e.g., .env, secrets)
• Stopping tracking of log or build files
• Cleaning up files that should be in .gitignore

git rm --cached .env
git commit -m "Remove .env from tracking"

You can combine this with .gitignore. See Gitignore examples.

git rm vs git rm --cached

The key difference between git rm and git rm --cached is how they affect your local files.

For related cleanup commands, check Git clean command explained.

rm -rf Command vs git rm -rf

What is rm -rf command?

The rm -rf command is a Linux/Unix command used to forcefully delete files and directories recursively from the filesystem.

rm -rf folder/

This command does not involve Git and permanently deletes files without tracking.

Why rm -rf is dangerous

The rm -rf command is powerful but risky because:

• It deletes files permanently without confirmation
• It does not maintain any history
• Mistakes cannot be easily undone

For example:

rm -rf *

This can wipe entire directories instantly, so always double-check before executing.

git rm -rf vs rm -rf comparison

Although both commands remove files recursively, they behave very differently.

If you accidentally use rm, Git will detect missing files but cannot restore them automatically unless they exist in history.

To safely manage deletions and history, also review Git reset examples and Git revert command explained.

Common Errors and Fixes

error: the following file has changes staged in the index

This error occurs when you try to remove a file that has staged or modified changes. Git prevents deletion to avoid accidental data loss.

To fix this, you can either commit the changes first or force the removal using the -f option.

git rm -f file.txt

Alternatively, if you want to discard changes safely, use:

git restore file.txt

For more ways to handle staged changes, refer to Git unstage files explained.

fatal: pathspec did not match any files

This error usually means the file you are trying to remove does not exist in the current directory or is not tracked by Git.

Common reasons include:

• Typo in file name
• File already deleted
• File is untracked

To verify, check the current status:

git status

If the file is untracked, you can remove it using:

rm file.txt

Or clean all untracked files using:

git clean -fd

Learn more in Git remove untracked files.

git rm not working

If git rm is not working as expected, check the following:

• Ensure the file is tracked (git status)
• Verify correct file path
• Check for local modifications (use -f if needed)

Example:

git rm -f file.txt

If your goal is only to untrack the file (not delete it locally), use:

git rm --cached file.txt

For alternative approaches, see Git reset examples and Git restore command explained.

Summary

The git rm command is used to remove files from both the working directory and the Git repository while tracking the deletion in version history.

• Use git rm to delete tracked files safely
• Use git rm -r to remove directories
• Use git rm --cached to untrack files without deleting them locally
• Use git rm -f when files have staged or modified changes
• Avoid using rm -rf for tracked files, as it bypasses Git tracking

Understanding when and how to use git rm helps you manage repositories more effectively and avoid accidental data loss.

Official Documentation

For complete and authoritative details on the git rm command and related topics, refer to the official Git documentation:

• git rm Documentation
• git restore Documentation
• git reset Documentation
• git clean Documentation
• git reflog Documentation

These resources provide detailed explanations, advanced options, and edge cases directly from the Git maintainers.