explaingit

newren/git-filter-repo

★ 12,364PythonAudience · developerComplexity · 2/5Setup · easy

TLDR

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.

Mindmap

mindmap
  root((git-filter-repo))
    What it does
      Rewrite Git history
      Remove files
      Scrub secrets
    Use cases
      Extract subdirectory
      Delete large files
      Remove passwords
    Tech stack
      Python script
      Git 2.36+
    Audience
      Developers
      DevOps engineers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Remove a large binary file accidentally committed from the entire history of a Git repository.

USE CASE 2

Scrub a password or API key that was accidentally checked into a commit from all historical commits.

USE CASE 3

Extract a subdirectory from a repository into its own standalone repository while preserving commit history.

USE CASE 4

Rename files or directories consistently across all historical commits in a repository.

Tech stack

PythonGit

Getting it running

Difficulty · easy Time to first run · 5min

Requires Git 2.36.0+ and Python 3.6+.

In plain English

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.

Copy-paste prompts

Prompt 1
Using git-filter-repo, give me the exact command to permanently remove a file named secrets.env from all commits in my repository history.
Prompt 2
I need to extract the src/frontend subdirectory from my Git repo into its own new repository while keeping the commit history. What git-filter-repo command does this?
Prompt 3
How do I use git-filter-repo to remove all files larger than 50MB from my repository history to reduce its size?
Prompt 4
Show me the git-filter-repo equivalent of the old filter-branch command: git filter-branch --tree-filter 'rm -f passwords.txt' HEAD
Open on GitHub → Explain another repo

← newren on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.