Skip to main content

​
git-filter-repo

Quickly rewrite git repository history (filter-branch replacement)

git-filter-repo is a versatile tool for rewriting history, which includes capabilities not found anywhere else. It roughly falls into the same space as git filter-branch but without the poor performance, with far more capabilities, and with a design that scales beyond trivial rewriting cases.
git-filter-repo is now recommended by the git project instead of git filter-branch.

​
Why git-filter-repo?

Lightning Fast

Orders of magnitude faster than filter-branch for non-trivial repositories

Powerful Filtering

Path-based filtering, content replacement, commit message rewriting, and more

Safe by Design

Detects and requires fresh clones, automatic cleanup, intelligent safety checks

Library & CLI

Use as a command-line tool or Python library for custom filtering scripts

​
Key Features

  • Fast repository history rewriting — Multiple orders of magnitude faster than filter-branch
  • Path-based filtering — Keep or remove specific paths with simple flags
  • File and directory renaming — Easily restructure your repository layout
  • Repository analysis — Identify large files and directories before filtering
  • Commit message rewriting — Update commit messages with new hashes automatically
  • Tag renaming and filtering — Rename or filter tags during the rewrite
  • Python library API — Write custom filtering scripts leveraging the core engine
  • Automatic cleanup — Repository optimization and cleanup happens automatically

​
Use Cases

git-filter-repo excels at common repository maintenance tasks:
Extract a portion of your repository while preserving history, perfect for splitting monorepos or creating focused repositories.
Permanently remove passwords, API keys, or other sensitive data that was accidentally committed.
Move files and directories around while maintaining full commit history.
Remove large files that are no longer needed to reduce repository size.
Update commit messages to reference new commit IDs after filtering.

​
How It Works

At its core, git-filter-repo works by running: 
git fast-export <options> | filter | git fast-import <options>
git-filter-repo not only launches this pipeline but also serves as the ‘filter’ in the middle, and does additional work to make it a well-rounded filtering tool. It provides both a simple command-line interface for common operations and a powerful library for complex custom filtering.

​
Prerequisites

Before installing git-filter-repo, ensure you have:
  • Git >= 2.36.0
  • Python >= 3.6

​
Quick Example

Here’s a simple example that extracts a subdirectory, moves it to a new location, and renames tags: 
git filter-repo --path src/ --to-subdirectory-filter my-module --tag-rename '':'my-module-'
This single command:
  1. Keeps only files under src/
  2. Moves everything into a new my-module/ directory
  3. Prefixes all tags with my-module-
This is just the beginning. git-filter-repo can handle much more complex filtering operations through its command-line options and Python API.

​
Next Steps

Installation

Install git-filter-repo on your system

Quickstart

Run your first filtering operation

Command Reference

Explore all command-line options

Examples

See common filtering patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us