东升汇文化产业园：鼎新文化创造 坚持文化进步

git filter-branch is a powerful tool for rewriting Git history. It can modify the author information in the commit, delete sensitive files or large files, reconstruct directory structure, etc.; 2. You must back up the warehouse before use, and avoid rewriting history at will in the shared warehouse to avoid disrupting collaboration; 3. It is recommended to use a safer and more efficient git filter-repo instead of filter-branch, but understanding filter-branch helps to master the underlying principles and maintain old scripts; 4. After execution, you need to clean up the original references and run garbage collection to completely remove old data to ensure that sensitive information is permanently deleted.

Rewriting your entire Git history is a powerful but dangerous operation — and git filter-branch was historically the go-to tool for it. While newer tools like git filter-repo are now recommended, understanding how git filter-branch works helps you grap what's really happening under the hood when you rewrite history.

Here's how to use git filter-branch responsible — and what you should consider before doing it.

What Is git filter-branch ?

git filter-branch lets you rewrite commits across your entire Git history by applying filters. You can:

• Remove sensitive data (like passwords or keys)
• Change author names or emails globally
• Delete large files that shouldn't have been committed
• Split or merge directories
• Clean up commit messages

Each commit gets rewritten from the root onward, producing a new history with altered content.

?? Warning: This changes SHA-1 hashes of all affected commits. If the repo is shared, this can break collaboration unless everyone resets their local repos.

Common Use Cases and Commands

1. Change Author Information Globally

If you've used the wrong email or name in past commits:

 git filter-branch --env-filter '
OLD_EMAIL="wrong@email.com"
CORRECT_NAME="Your Name"
CORRECT_EMAIL="correct@email.com"

if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ]; then
    export GIT_COMMITTER_NAME="$CORRECT_NAME"
    export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"
fi
if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ]; then
    export GIT_AUTHOR_NAME="$CORRECT_NAME"
    export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"
fi
' --tag-name-filter cat -- --all

This updates both author and committer fields wherever the old email appears.

2. Remove a Large File from History

Say you accidentally committed bigfile.log :

 git filter-branch --tree-filter 'rm -f path/to/bigfile.log' --prune-empty HEAD

Or better (faster), using --index-filter :

 git filter-branch --index-filter \
'git rm --cached --ignore-unmatch bigfile.log' \
--prune-empty --tag-name-filter cat -- --all

The --index-filter is faster because it operates on the staging area without checking out each commit.

3. Move Files into a Subdirectory

To restruct your project so all old files live under legacy/ :

 git filter-branch --tree-filter '
mkdir -p legacy &&
mv * legacy/ 2>/dev/null || true
' --prune-empty -- --all

Note: Be careful with shell globs; they might miss dotfiles. Adjust accordingly.

4. Delete Sensitive Data Permanently

For removing credentials or secrets:

 git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch -r -- .env config/secrets.txt' \
--prune-empty --tag-name-filter cat -- --all

After this, also remove refs to old objects:

 rm -rf .git/refs/original/
git reflog expire --expire=now --all
git gc --aggressive --prune=now

This clears loose objects and repacks the repository.

Important Notes Before You Begin

• ? Backup your repo first. Run git clone again or zip the current state.
• ? Don't rewrite public history lightly. If others depend on the repo, coordinate carefully — rewriting shared branches causes pain.
• ? All downstream clones will need to rebase or reset to the new history.
• ? Consider using git filter-repo instead — it's faster, safer, and actively maintained.

Example with git filter-repo (recommended alternative):

 # Install via pip: pip install git-filter-repo
git filter-repo --email-callback 'return email.replace(b"old@com", b"new@com")'

It avoids many pitfalls of filter-branch .

Final Cleanup After filter-branch

After running filter-branch , clean up leftover references:

 git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d
git reflog expire --expire=now --all
git gc --prune=now --aggressive

This ensures old objects are garbage-collected and not just hidden.

Basically, git filter-branch gives you full control — but with great power comes great responsibility. Most people today should reach for git filter-repo , but knowing how filter-branch works helps debug edge cases or maintain older scripts.

The above is the detailed content of Rewriting Your Entire Git History with Filter-Branch. For more information, please follow other related articles on the PHP Chinese website!