How to fix WARNING: git-filter-branch has a glut of gotchas generating mangled history rewrites. Hit Ctrl-C before proceeding to abort, then use an alternative filtering tool such as 'git filter-repo' in Git

GitINTERMEDIATEMEDIUM

This warning appears when running git filter-branch, indicating that the command is deprecated due to numerous safety and performance issues. Git recommends using git-filter-repo as a faster, safer alternative.

What this error means

When you run `git filter-branch`, Git displays this warning because the command has been officially deprecated. The Git project has determined that git-filter-branch is "riddled with gotchas resulting in various ways to easily corrupt repos or end up with a mess worse than what you started with." The warning is not an error—your command will still run if you don't press Ctrl-C. However, Git is strongly advising you to use `git filter-repo` instead, which is a Python-based tool that was designed from the ground up to avoid filter-branch's problems. The issues with git-filter-branch are fundamental to its design and cannot be fixed in a backward-compatible way. It works by checking out every commit, running shell commands to transform the working copy, and then creating new commits. This approach is inherently slow (orders of magnitude slower than alternatives) and prone to subtle bugs based on your shell environment, OS, and special characters in filenames or author names.

How to fix "WARNING: git-filter-branch has a glut of gotchas generating mangled history rewrites. Hit Ctrl-C before proceeding to abort, then use an alternative filtering tool such as 'git filter-repo'"

1Install git-filter-repo (recommended replacement)

The officially recommended replacement is git-filter-repo. Install it using your package manager or pip:

bash

# Using pip (works on all platforms)
pip3 install git-filter-repo

# On macOS with Homebrew
brew install git-filter-repo

# On Ubuntu/Debian
sudo apt install git-filter-repo

# On Arch Linux
sudo pacman -S git-filter-repo

Verify installation:

bash

git filter-repo --version

2Create a fresh clone before rewriting history

git-filter-repo requires a fresh clone as a safety measure. This prevents accidental corruption of your main working directory:

bash

# Clone your repository fresh
git clone --mirror https://github.com/user/repo.git repo-filter
cd repo-filter

# Or if you have a local repo, create a fresh clone
git clone --no-local /path/to/original /path/to/fresh-clone
cd /path/to/fresh-clone

Important: Never run history rewriting commands on your only copy of a repository.

3Convert your filter-branch command to filter-repo

Common conversions from filter-branch to filter-repo:

Remove a file from all history:

bash

# Old (filter-branch)
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch path/to/file' \
  --prune-empty -- --all

# New (filter-repo)
git filter-repo --invert-paths --path path/to/file

Remove a directory from all history:

bash

# Old (filter-branch)
git filter-branch --force --index-filter \
  'git rm -rf --cached --ignore-unmatch path/to/dir/' -- --all

# New (filter-repo)
git filter-repo --invert-paths --path path/to/dir/

Change author email in all commits:

bash

# New (filter-repo with mailmap)
echo "New Name <[email protected]> <[email protected]>" > .mailmap
git filter-repo --mailmap .mailmap

4Remove large files using BFG Repo-Cleaner (alternative)

For the specific case of removing large files, BFG Repo-Cleaner is another excellent alternative:

bash

# Download BFG (requires Java)
wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar

# Remove files larger than 100MB
java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 100M repo.git

# Remove specific files by name
java -jar bfg-1.14.0.jar --delete-files "*.zip" repo.git

# Clean up and garbage collect
cd repo.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive

BFG is 10-720x faster than git-filter-branch and simpler for file removal tasks.

5Suppress the warning if you must use filter-branch

If you have a specific reason to continue using filter-branch (e.g., maintaining legacy scripts), you can suppress the warning:

bash

# Set environment variable before running
export FILTER_BRANCH_SQUELCH_WARNING=1
git filter-branch ...

# Or inline with the command
FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch --tree-filter 'rm -f password.txt' HEAD

Warning: This doesn't fix any of filter-branch's problems—it just hides the warning. The command will still be slow and potentially unreliable.

6Force push and notify collaborators

After rewriting history with any tool, you need to force push and have collaborators sync:

bash

# Push the rewritten history
git push origin --force --all
git push origin --force --tags

# Collaborators should re-clone or reset
git fetch origin
git reset --hard origin/main

Important: Rewriting shared history affects everyone. Coordinate with your team before force pushing.

Advanced notes

### Why filter-branch Has "a Glut of Gotchas"

The official Git documentation lists several fundamental problems with filter-branch:

1. Performance: It checks out every commit to disk, which is extremely slow for large repositories. A rewrite that takes hours with filter-branch might take minutes with filter-repo.

2. Cross-platform issues: Shell commands behave differently on BSD (macOS) vs GNU (Linux). A filter that works on your Mac might silently corrupt history on a colleague's Linux machine.

3. Encoding and special characters: Spaces in filenames, non-ASCII characters, unusual author names, and invalid timezones can all cause subtle, hard-to-detect corruption.

4. Error handling: Errors may not be visible, or may only appear after a long wait. You might not know your filter failed until the rewrite is complete.

5. Old/new history mixing: It's easy to accidentally merge old refs back into rewritten history, undoing your work and creating duplicate commits.

### Using filter-lamely as a Transition Tool

If you have many filter-branch scripts and need a quick performance boost without rewriting them, you can use filter-lamely—a compatibility shim that runs filter-branch syntax through filter-repo:

bash

# Download filter-lamely from git-filter-repo repository
# Then replace 'git filter-branch' with 'filter-lamely' in your scripts

This gives partial performance improvements but doesn't fix the safety issues.

### Removing Sensitive Data

If you're removing secrets, passwords, or API keys from history:

1. Rotate the credentials immediately—the secrets are already compromised if pushed publicly
2. Use git filter-repo --replace-text with a replacements file
3. Remember that GitHub/GitLab may cache old commits; contact support for full removal
4. Consider using tools like truffleHog or git-secrets to prevent future leaks

### Tags and Refs

git-filter-repo handles tags correctly by default. It rewrites tag objects to point to the new commits and updates the refs. filter-branch has documented bugs where multiple tags mapping to the same name are silently overwritten.

How to fix WARNING: git-filter-branch has a glut of gotchas generating mangled history rewrites. Hit Ctrl-C before proceeding to abort, then use an alternative filtering tool such as 'git filter-repo' in Git

What this error means

Typical symptoms

Common causes

How to fix "WARNING: git-filter-branch has a glut of gotchas generating mangled history rewrites. Hit Ctrl-C before proceeding to abort, then use an alternative filtering tool such as 'git filter-repo'"

Advanced notes

Related errors

Official resources & further reading