How do you use git filter-repo to strip a path from every commit in a repo?

## What the tool is `git filter-repo` is a single-purpose history-rewriting program. It is not a builtin — it ships separately from Git and is invoked as `git filter-repo`. It reads the whole object stream once, applies your filters, and writes a new history. That single-pass design is why it finishes in seconds or minutes on repositories where the older `git filter-branch` would run for hours. ## Selecting paths Path arguments are **inclusive** by default: naming a path means "the rewritten history contains only this". - `--path <path>` matches a file or a directory prefix. - `--path-glob '<pattern>'` matches a shell-style glob. - `--path-regex '<regex>'` matches a regular expression. All may be repeated and mixed; the selection is their union. Adding `--invert-paths` inverts the whole selection into "everything except these". So: - extract a subdirectory into its own project: `git filter-repo --subdirectory-filter services/billing` - purge a leaked file: `git filter-repo --path config/prod.env --invert-paths` - purge a whole class of files: `git filter-repo --path-glob '*.pfx' --invert-paths` Related filters worth knowing: `--path-rename old:new` moves a path across all of history, and `--subdirectory-filter <dir>` promotes a subdirectory to the repository root. ## The fresh-clone rule By default the tool aborts unless it is running in a freshly cloned repository. This is deliberate: the rewrite is not undoable, and a fresh clone means the original still exists somewhere untouched. `--force` overrides the check, and you should reach for it only when you personally know an intact copy exists. The recommended shape is therefore: clone, rewrite in the clone, inspect the result, then push. ## What it does after filtering Without being asked, `git filter-repo`: - rewrites **all** refs — branches, tags and notes — not just the current branch; - drops commits that became empty because their only changes touched removed paths; - writes `.git/filter-repo/commit-map` and `.git/filter-repo/ref-map`, mapping every old SHA to its replacement (or to zeros when the commit was dropped); - expires reflogs and garbage-collects, so the old objects are genuinely gone from that copy; - removes the `origin` remote, forcing a deliberate `git remote add` before anything can be pushed. That last behaviour surprises people and is the point: publishing a rewritten history should be a decision, not an accident. ## The consequence you must state out loud Rewriting the *first* affected commit changes its SHA, which changes its children's SHAs, and so on to every tip. In practice the entire history from the earliest touched commit forward is new. Consequences worth naming: - Every existing clone is now incompatible; a plain `git pull` will try to merge two parallel histories. - Anything that stored a commit SHA — release notes, deployment records, issue references, submodule pointers — now names a commit that exists only in old copies. - Signed commits lose their signatures, because a signature covers the old commit content. - The push must be forced and must cover every rewritten ref, not just the branch you were looking at. ## Verifying before you push Cheap checks that catch mistakes: `git log --all --oneline -- <removed-path>` should output nothing; `git count-objects -vH` should show the expected size drop; `git log --oneline | wc -l` shows how many commits were pruned as empty. Running `git filter-repo --analyze` *before* filtering writes size and path reports under `.git/filter-repo/analysis/`, so you can choose the right paths in the first place. ## When not to use it If the unwanted content exists only in commits that were never published, an ordinary local fixup is cheaper and disturbs nobody. Reach for a bulk rewrite when the content is spread across published history and no cheaper edit reaches it.