What it does
git-filter-repo is a command-line utility and Python library for rewriting Git history. It can filter commits and file contents for jobs such as removing a path or splitting a subdirectory into a new repository. The upstream Git project recommends it in place of `git filter-branch`. Because a rewrite creates new commit identities, it is a specialist cleanup tool rather than an ordinary way to edit a working tree.
Use git-filter-repo when the goal is to change repository history, not just remove a file from the current checkout. A first task might be extracting a subtree or purging a path from all commits. The official README recommends a fresh clone and documents a safety check that stops when the repository does not look like a fresh clone; --force bypasses that safeguard. Keep a separate backup and review the exact filter before pushing rewritten history, since collaborators may need to rebase or reclone.
The project requires Git 2.36 or newer and Python 3.6 or newer. Basic use is a single Python script on PATH, while custom Python filtering scripts can use its library. The main tool is MIT-licensed; the repository notes that its test harness and examples have separate license terms, so check the relevant files when redistributing those parts.
Strengths
- Provides path and content filters for history-rewriting tasks, including repository cleanup and subdirectory extraction.
- The main tool is distributed as a single script for basic use, and the project also exposes a Python library for custom filters.
Watch out for
- A history rewrite changes commit identities and can disrupt collaborators or existing remote references.
- The tool intentionally refuses some repositories that do not look like fresh clones; bypassing that safety check with `--force` requires extra care.
- The repository contains files with separate licenses for its test harness and examples.
Best for
- Removing a file or path from a repository's historical commits.
- Extracting a directory into a repository with rewritten history.
- Building a specialized Git history filter in Python.
Sources
- git-filter-repo official README and usage overview (Oct 26, 2026)
- git-filter-repo usage documentation (Oct 26, 2026)
- newren/git-filter-repo official repository (Oct 26, 2026)
- git-filter-repo license information (Oct 26, 2026)