git-filter-repo is a command-line tool for rewriting git repository history that replaces git filter-branch with better performance and more capabilities.
The tool solves the problem of needing to modify git history—removing sensitive data, restructuring repositories, or cleaning up commits—in cases where the built-in git filter-branch is too slow or lacks necessary features. It works by providing both a straightforward command-line interface for common rewriting tasks and an underlying Python library that developers can use to build specialized history rewriting tools for their own needs.
Most users will interact with filter-repo as a simple command-line tool, though the README notes it also exposes a library for creating entirely new history rewriting tools. The README explicitly compares it to git filter-branch, BFG Repo Cleaner, and fast-export/fast-import approaches. Against filter-branch, the tool offers significantly better performance and far more capabilities with a design that scales beyond trivial rewriting cases. The git project itself now recommends filter-repo instead of filter-branch. Installation is minimal for basic use—the entire tool is a single Python script that can be placed in your PATH—though more involved setup is available for those wanting to use it as a library, install documentation, or run contributed examples.
The project maintains a single-file Python implementation to keep basic installation trivial across many systems. The tool requires git 2.36.0 or later and Python 3.6 or later. The README includes a comprehensive user manual and points to contributed example scripts demonstrating specialized use cases built on the library.
