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.
git filter-branch --index-filter 'git rm -q --cached --ignore-unmatch secrets.txt' -- --all
Try it
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.
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
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 catto 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-filterover--tree-filterwhenever the change is about which files exist. - Warning pause. Git sleeps for several seconds and prints a warning unless
FILTER_BRANCH_SQUELCH_WARNING=1is 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.