TIL: Chopping repos with git-filter-repo

Git

Recently needed to extract some utility scripts from a monorepo into their own repository and wanted to preserve git history. There is git filter-branch but is a bit clunky to use and comes with this big fat warning. Enter git-filter-repo.

It can:

  • Strip large files from the repository’s entire history
  • Extract wanted paths and their history (stripping everything else)
  • Move all files into a subdirectory or restructure file layout

A common use case is removing sensitive files from history - if you accidentally committed credentials, this is how you wipe them completely from git history (not that it matters if it was ever public). It’s also silly fast, especially for what it does.

Here’s how I extracted the tooling:

$ git clone git@github.com:czak/original-repo.git tooling-repo
$ cd tooling-repo

# Keep only utils, notes, and the Makefile. Also move utils to src:
$ git filter-repo \
  --path utils/ --path-rename utils/:src/ \
  --path notes/ \
  --path Makefile

$ ls -1a
./
../
.git/
notes/
src/
Makefile

The --path flag keeps files/directories matching the pattern and removes everything else. You can use --path multiple times.

Take a look at the examples. If you made it to this note then git-filter-repo might be what you need. It’s an excellent Swiss Army knife (or a scalpel?) for git.