How to fix error: the following file has local modifications: file.txt in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 171 views

This error occurs when you try to remove a file with git rm that has uncommitted changes. Git blocks the removal to prevent accidental data loss. Use --cached to keep the file or -f to force removal.

Quick fix

Fixes error: the following file has local modifications: file.txt

git status
  1. Check the file status
  2. Option A: Commit changes before removing
  3. Option B: Keep file on disk with --cached
  4. Option C: Force removal with -f
git — error
git status
error: the following file has local modifications: file.txt

What this error means

When you run `git rm` on a file, Git performs a safety check to ensure the file in your working directory matches the version in the current HEAD commit. If the file has been modified but not committed, Git refuses to remove it and displays this error. This is a deliberate safety feature, not a bug. The files being operated on must be identical to the files in the current HEAD. If there is a discrepancy between the HEAD version and the working tree version, Git blocks the removal to prevent you from accidentally losing uncommitted work. The error message helpfully suggests two options: use `--cached` to keep the file on disk but remove it from Git tracking, or use `-f` to force removal (which permanently deletes your local changes).

Typical symptoms

  • Running git rm on a file produces 'has local modifications' error
  • The error suggests using --cached or -f to proceed
  • The file has been edited but changes are not committed
  • git status shows the file as modified
  • Attempting to remove multiple files where at least one is modified

Common causes

  1. The file has been modified since the last commit (most common)
  2. The file has been staged but the staged content differs from HEAD
  3. You edited the file and forgot to commit before trying to remove it
  4. A script or build process modified the file unexpectedly
  5. You are trying to clean up files but have unsaved work
  6. Merge or rebase left the file in a modified state

How to fix "error: the following file has local modifications: file.txt"

1Check the file status

First, understand what changes exist in the file:

bash
git status

This shows whether the file is modified, staged, or both. To see the actual changes:

bash
git diff file.txt

This helps you decide whether to save the changes or discard them.

2Option A: Commit changes before removing

If you want to preserve your changes in the Git history before removing the file:

bash
git add file.txt
git commit -m "Save final version of file.txt before removal"
git rm file.txt
git commit -m "Remove file.txt"

This creates a clean history showing the file's final state.

3Option B: Keep file on disk with --cached

If you want to stop tracking the file in Git but keep it on your local filesystem:

bash
git rm --cached file.txt

This removes the file from the Git index (staging area) but leaves it in your working directory. The file will appear as untracked after this command.

Common use case: Adding a file to .gitignore that was previously tracked:

bash
echo "file.txt" >> .gitignore
git rm --cached file.txt
git commit -m "Stop tracking file.txt"
4Option C: Force removal with -f

If you want to remove the file and discard your local changes permanently:

bash
git rm -f file.txt

WARNING: This permanently deletes your uncommitted changes with no way to recover them. Make sure you don't need those changes before using this option.

The -f flag overrides Git's safety check that normally prevents removal of files with local modifications.

5Use dry run to preview removal

Before removing files (especially with wildcards), use the dry-run option to see what would be removed:

bash
git rm -n file.txt
git rm --dry-run "*.log"

This outputs which files would be removed without actually deleting anything. Especially important when using glob patterns.

6Stash changes before removal

If you're unsure whether you need the changes, stash them first:

bash
git stash push -m "backup before removal" file.txt
git rm file.txt

Later, if you need the changes back:

bash
git stash pop

This provides a safety net while still allowing you to proceed with the removal.

7Undo an accidental git rm

If you ran git rm by mistake (without -f) and want to restore the file:

bash
git restore --staged file.txt
git restore file.txt

Or using the older syntax:

bash
git reset HEAD file.txt
git checkout -- file.txt

Note: If you used git rm -f on a file with uncommitted changes, those changes are lost permanently.

Advanced notes

### Understanding --cached vs -f

| Flag | Removes from Index | Removes from Disk | Local Changes |
|------|-------------------|-------------------|---------------|
| --cached | Yes | No (file stays) | Preserved in working directory |
| -f | Yes | Yes | Permanently lost |

Choose --cached when you want to untrack a file but keep it locally (e.g., config files, build artifacts).
Choose -f only when you're certain you don't need the uncommitted changes.

### Removing Multiple Files

When removing multiple files, Git checks each one. If any file has local modifications, the entire operation fails. Use wildcards carefully:

bash
# Safe: preview first
git rm -n "*.tmp"

# Force remove all matching files
git rm -f "*.tmp"

### Staged vs Working Directory Changes

Git's safety check considers both:
- Staged changes: Content in the index differs from HEAD
- Working directory changes: Content on disk differs from HEAD

If you have staged changes you want to keep, commit them first. The --cached flag still works if staged content differs from HEAD.

### Recursive Directory Removal

To remove a directory and all its contents:

bash
# Will fail if any file has local modifications
git rm -r directory/

# Force remove entire directory
git rm -rf directory/

Be extra careful with -rf on directories as it bypasses all safety checks.

### Why Git Has This Safety Feature

The git rm command stages a file deletion for the next commit. If Git allowed removing modified files without warning, you could easily lose work that hasn't been committed anywhere. Unlike committed changes (which can be recovered from Git history), uncommitted local changes exist only on your disk.

Frequently asked questions

What does "error: the following file has local modifications: file.txt" mean?
When you run git rm on a file, Git performs a safety check to ensure the file in your working directory matches the version in the current HEAD commit. If the file has been modified but not committed, Git refuses to remove it and displays this error. This is a deliberate safety feature, not a bug.
How do I fix "error: the following file has local modifications: file.txt"?
This error occurs when you try to remove a file with git rm that has uncommitted changes. Git blocks the removal to prevent accidental data loss. Use --cached to keep the file or -f to force removal.
What causes "error: the following file has local modifications: file.txt"?
The file has been modified since the last commit (most common) The file has been staged but the staged content differs from HEAD You edited the file and forgot to commit before trying to remove it
Is the "error: the following file has local modifications: file.txt" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading