git-filter-repo

What it is and what it does

git-filter-repo is a command-line tool and Python library for rewriting git repository history. It handles tasks like removing files, renaming paths, extracting subdirectories, and cleaning sensitive data across all commits. The tool is designed as a modern replacement for git filter-branch, which the git project itself now recommends against due to poor performance and safety issues.

Most users interact with it as a CLI tool with flags for common rewrites. For specialized needs, the package also exposes a library interface so developers can build custom history rewriting tools. It requires git >= 2.22.0 and Python >= 3.6, and has no external Python dependencies beyond the standard library.

Use it for:

• Remove accidentally committed secrets, large files, or sensitive data from all commits in a repository's history.
• Extract a subdirectory from a monorepo into a standalone repository with clean history.
• Rename file paths or directory structures across an entire repository's commit history.
• Migrate repositories between hosting platforms while cleaning up or restructuring history.
• Build a custom history rewriting tool by leveraging the filter-repo library for domain-specific transformations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Rewrites git repository history efficiently, replacing files, removing sensitive data, extracting subdirectories, and renaming paths across commits—faster and more capable than git filter-branch.

Yes. It is actively maintained, has no dependencies, installs easily, and solves a real problem (git history rewriting) that git filter-branch handles poorly. The MIT license is permissive. No known vulnerabilities. Recommended by the git project itself as the successor to filter-branch. Install if you need to rewrite git history or build tools that do so.

Install

git-filter-repo on PyPI

pip install git-filter-repo

uv add git-filter-repo

poetry add git-filter-repo

Installing git-filter-repo

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance (last commit 2026-07-09) and stable release cycle. Supports Python 3.6 through 3.12 and PyPy.

License in practice

MIT license (permissive): you can use, modify, and distribute freely with minimal restrictions. No copyleft obligations.

Quickstart

pip install git-filter-repo

git filter-repo --path src/ --path-rename src/:my-module/

Requires git >= 2.22.0 (some features need >= 2.24.0) and Python 3 >= 3.6; git must be installed and in PATH.

Verify before relying

• Whether the library API (for creating custom history rewriting tools) is stable and well-documented for programmatic use beyond the CLI.
• Performance characteristics on very large repositories (commit count, object count) compared to stated claims.

Package facts

Evidence: git_filter_repo-2.47.0-py3-none-any.whl

Tags

More Utilities packages