Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Merging and Rebasing

git filter-branch command

Reference for git filter-branch: remove files, change authors or extract a subdirectory across all commits, with the filters, safety backups, and why filter-repo is preferred.

git filter-branch rewrites a whole range of history by running filters over every commit: change the tree, edit the message, replace the author, or keep only one subdirectory. Each commit is rebuilt in turn, so all descendants get new IDs, as do tags you ask it to rewrite.

It is the oldest tool for the job and still ships with Git, but Git's own documentation warns that it has many pitfalls, and it prints a warning every time you run it. For large repositories or serious clean-ups, prefer the separate git filter-repo tool when you can install it (it is not part of Git). Knowing filter-branch is still useful: it is everywhere in old scripts and Q&A answers, and it needs nothing but Git itself.

Terminal
git filter-branch --index-filter 'git rm -q --cached --ignore-unmatch secrets.txt' -- --all

Try it

Bash Remove a file from every commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Rewrite messages, authors and keep one directory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
                  [--env-filter <command>] [--tree-filter <command>]
                  [--index-filter <command>] [--parent-filter <command>]
                  [--msg-filter <command>] [--commit-filter <command>]
                  [--tag-name-filter <command>] [--prune-empty]
                  [--original <namespace>] [-d <directory>] [-f | --force]
                  [--state-branch <branch>] [--] [<rev-list options>...]
Filter What it runs and when
--env-filter Sets author and committer variables (GIT_AUTHOR_NAME, GIT_COMMITTER_EMAIL, dates, ...) before each commit is recreated.
--tree-filter Checks out each commit into a temporary directory, runs your command there, then records the result. Slow, because every commit is checked out.
--index-filter Runs against the index only, without a checkout. Much faster; use git rm --cached or git update-index inside it.
--parent-filter Reads the parent list from standard input, writes a new one to standard output.
--msg-filter Reads the old message on standard input, writes the new one.
--commit-filter Replaces the git commit-tree call, letting you skip commits (skip_commit "$@").
--tag-name-filter Rewrites tags that point at rewritten commits. Without it, tags keep pointing at the old commits.
--subdirectory-filter <dir> Keeps only history that touches the directory and makes it the new root.
--prune-empty Drops commits that become empty.
-f, --force Overwrite the refs/original/ backup of an earlier run.
-- and <rev-list options> Which refs to rewrite, for example --all or main. The -- separates them from filter options.

Returns: exit status 0 on success; non-zero if a filter command fails or the working tree is dirty.

Usage notes

  • Backups are kept. The old branch tips are saved under refs/original/. Remove them (git update-ref -d refs/original/refs/heads/main) before running garbage collection if you want old data gone.
  • Rewriting changes every ID after the first changed commit. Anyone who has the old history must re-clone or rebase their work. Do not rewrite shared branches casually.
  • Tags are not rewritten by default. Add --tag-name-filter cat to rewrite them under the same names.
  • Only the refs you list are rewritten. Without --all, other branches still point at the old history.
  • Prefer --index-filter over --tree-filter whenever the change is about which files exist.
  • Warning pause. Git sleeps for several seconds and prints a warning unless FILTER_BRANCH_SQUELCH_WARNING=1 is set. Scripts and the examples here set it.
  • Known pitfalls: it does not handle history with a very large number of files or commits well, may unintentionally keep empty commits, and cannot rewrite commit messages that mention other commit IDs.
  • To really remove a leaked secret, rotate it first. History rewriting does not remove copies others already fetched.