git-filter-repo
Quickly rewrite git repository history (filter-branch replacement)
A fast command-line tool for rewriting Git repository history, removing large files, scrubbing secrets, and extracting subdirectories, officially recommended over the older filter-branch.
git-filter-repo is a command-line tool for rewriting the history of a Git repository. Git tracks every change ever made to a codebase, and sometimes you need to clean up or restructure that history: removing a large file that was accidentally committed, extracting one folder into its own repository, or scrubbing a password that was mistakenly checked in. This tool handles those tasks.
It is the officially recommended replacement for an older built-in Git command called filter-branch, which the Git project itself has warned users to stop using because it is very slow on any repository of meaningful size and has subtle bugs that can silently produce incorrect results. git-filter-repo is multiple times faster than filter-branch and handles a much wider range of rewriting scenarios with fewer surprises.
The tool is distributed as a single Python script, which makes installation straightforward: download the file and put it somewhere your system can find it. It requires Git version 2.36.0 or higher and Python 3.6 or higher. For developers who need to do more than the built-in command-line flags allow, the script can also be used as a Python library to build custom history-rewriting tools.
Common use cases include: pulling one subdirectory out of a repository to create a standalone repo, renaming files or directories across all historical commits, and removing sensitive data or oversized files from the full commit history. The repository includes cheat sheets comparing filter-repo commands to equivalent commands in older tools, making it easier to switch from previous workflows.
This is a developer tool intended for people who work with Git on the command line.
Where it fits
- Remove a large binary file accidentally committed from the entire history of a Git repository.
- Scrub a password or API key that was accidentally checked into a commit from all historical commits.
- Extract a subdirectory from a repository into its own standalone repository while preserving commit history.
- Rename files or directories consistently across all historical commits in a repository.