Cheat Sheet

This cheat sheet provides quick reference for common git-filter-repo operations. Use the tabs below to navigate between different migration scenarios and common use cases.

Converting from filter-branch

filter-branch:

git filter-branch --tree-filter 'rm filename' HEAD
# or
git filter-branch --tree-filter 'rm -f filename' HEAD
# or (faster)
git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD

filter-repo:

git filter-repo --invert-paths --path filename

filter-branch:

git filter-branch --subdirectory-filter foodir -- --all

filter-repo:

git filter-repo --subdirectory-filter foodir

filter-branch:

git filter-branch --index-filter \
    'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
            GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
                    git update-index --index-info &&
     mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD

filter-repo:

git filter-repo --to-subdirectory-filter newsubdir

filter-branch:

git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
# or
git filter-branch --parent-filter \
    'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
# or (better)
git replace --graft $commit-id $graft-id
git filter-branch $graft-id..HEAD

filter-repo:

git replace --graft $commit-id $graft-id
git filter-repo --proceed

--proceed is needed because filter-repo errors out if no arguments are specified.

Removing text:filter-branch:

git filter-branch --msg-filter 'sed -e "/^git-svn-id:/d"'

filter-repo:

git filter-repo --message-callback '
    return re.sub(b"^git-svn-id:.*\n", b"", message, flags=re.MULTILINE)
    '

Adding text:filter-branch:

git filter-branch --msg-filter '
        cat &&
        echo "Acked-by: Bugs Bunny <[email protected]>"
    ' master~10..master

filter-repo:

git filter-repo --message-callback '
        return message + b"Acked-by: Bugs Bunny <[email protected]>\n"
    ' --refs master~10..master

filter-branch:

git filter-branch --env-filter '
    if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
    then
            [email protected]
    fi
    if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
    then
            [email protected]
    fi
    ' -- --all

filter-repo (using mailmap):

# Ensure '<[email protected]> <root@localhost>' is a line in .mailmap
git filter-repo --use-mailmap

filter-repo (using callback):

git filter-repo --email-callback '
  return email if email != b"root@localhost" else b"[email protected]"
  '

Both filter-repo alternatives also fix tagger emails, unlike the filter-branch example.

filter-branch:

git filter-branch --tree-filter '
    git ls-files -z "*.c" \
        | xargs -0 -n 1 clang-format -style=file -i
    '

filter-repo:

lint-history --relevant 'return filename.endswith(b".c")' \
    clang-format -style=file -i

lint-history is a contrib script that comes with git-filter-repo.

Converting from BFG Repo Cleaner

Stripping Big Blobs
Deleting Files
Removing Sensitive Content
Removing Files/Folders

BFG:

java -jar bfg.jar --strip-blobs-bigger-than 100M some-big-repo.git

filter-repo:

git filter-repo --strip-blobs-bigger-than 100M

BFG:

java -jar bfg.jar --delete-files id_{dsa,rsa} my-repo.git

filter-repo:

git filter-repo --use-base-name --path id_dsa --path id_rsa --invert-paths

BFG:

java -jar bfg.jar --replace-text passwords.txt my-repo.git

filter-repo:

git filter-repo --replace-text passwords.txt

For regex replacements using ”==>”, filter-repo uses \1, \2, etc. for replacement strings (Python style), while BFG uses $1, $2, etc. (Scala style).

BFG:

java -jar bfg.jar --delete-folders .git --delete-files .git \
    --no-blob-protection my-repo.git

filter-repo:

git filter-repo --invert-paths --path-glob '*/.git' --path .git

The glob */.git matches .git directories one or more levels deep (git-style glob). The --path .git handles the toplevel case.

Common Operations

File Operations

Purge a large list of files

Create a file with paths to delete (one per line):

git filter-repo --invert-paths --paths-from-file ../DELETED_FILENAMES.txt

Removing a directory

git filter-repo --path node_modules/electron/dist/ --invert-paths

Removing paths with a certain extension

git filter-repo --invert-paths --path-glob '*.xsa'

Or using a callback:

git filter-repo --filename-callback '
    if filename.endswith(b".xsa"):
        return None
    return filename'

Extract library from subdirectory

Keep src/some-folder/some-feature/ but rename it to src/:

git filter-repo \
    --path src/some-folder/some-feature/ \
    --path-rename src/some-folder/some-feature/:src/

Only keep files from specific branches

git ls-tree -r ${BRANCH1} >../my-files
git ls-tree -r ${BRANCH2} >>../my-files
sort ../my-files | uniq >../my-relevant-files
git filter-repo --paths-from-file ../my-relevant-files

Content Modifications

Replace words in all commit messages

git filter-repo --message-callback 'return message.replace(b"stuff", b"task")'

Remove spaces at end of lines

git filter-repo --replace-text <(echo 'regex:[\r\t ]+(\n|$)==>\n')

Replace binary blob in history

Replace blob with hash f4ede2e944868b9a08401dafeb2b944c7166fd0a:

git filter-repo --blob-callback '
    if blob.original_id == b"f4ede2e944868b9a08401dafeb2b944c7166fd0a":
        blob.data = open("../alternative-file.jpg", "rb").read()
'

Or using git replace:

git replace -f f4ede2e944868b9a08401dafeb2b944c7166fd0a \
    $(git hash-object -w ../alternative-file.jpg)
git filter-repo --proceed

Renormalize line endings and add .gitattributes

contrib/filter-repo-demos/lint-history dos2unix
# Edit .gitattributes
contrib/filter-repo-demos/insert-beginning .gitattributes

Filename Filtering

Include and exclude rules

Include all files under src/ except src/README.md:

git filter-repo --filename-callback '
    if filename == b"src/README.md":
        return None
    if filename.startswith(b"src/"):
        return filename
  return None'

Remove files with backslashes

git filter-repo --filename-callback 'return None if b"\\" in filename else filename'

Convert NFD filenames to NFC

git filter-repo --filename-callback '
    import unicodedata
    try:
       return bytearray(unicodedata.normalize("NFC", filename.decode("utf-8")), "utf-8")
    except:
      return filename
'

Author/Committer Modifications

Set committer of last few commits

git filter-repo --refs main~5..main --commit-callback '
    commit.committer_name = b"My Wonderful Self"
    commit.committer_email = b"[email protected]"
'

Handle special characters in names

git filter-repo --refs main~5..main --commit-callback '
    if commit.author_email == b"[email protected]":
        commit.author_name = "Raphaël González".encode()
        commit.author_email = b"[email protected]"
'

Advanced Operations

Add files to root commits

git filter-repo --commit-callback "if not commit.parents: commit.file_changes += [
    FileChange(b'M', b'README.md', b'$(git hash-object -w '/path/to/README.md')', b'100644'), 
    FileChange(b'M', b'src/.gitignore', b'$(git hash-object -w '/path/to/.gitignore')', b'100644')]"

Update submodule hashes

Update submodule at src/my-submodule according to mapping:

git filter-repo --file-info-callback '
    if filename == b"src/my-submodule" and blob_id == b"edf570fde099c0705432a389b96cb86489beda09":
        blob_id = b"9cce52ae0806d695956dcf662cd74b497eaa7b12"
    if filename == b"src/my-submodule" and blob_id == b"644f7c55e1a88a29779dc86b9ff92f512bf9bc11":
        blob_id = b"88b02e9e45c0a62db2f1751b6c065b0c2e538820"
    return (filename, mode, blob_id)
'

Replace PNGs with compressed versions

First identify the blob IDs:

git log -1 --raw --no-abbrev ${COMMIT_WHERE_YOU_COMPRESSED_PNGS}

Then replace:

git filter-repo --file-info-callback '
    if filename == b"resources/foo.png" and blob_id == b"edf570fde099c0705432a389b96cb86489beda09":
        blob_id = b"9cce52ae0806d695956dcf662cd74b497eaa7b12"
    if filename == b"resources/bar.png" and blob_id == b"644f7c55e1a88a29779dc86b9ff92f512bf9bc11":
        blob_id = b"88b02e9e45c0a62db2f1751b6c065b0c2e538820"
    return (filename, mode, blob_id)
'

Remove commits older than N days

This changes every commit hash and discards history. Use with caution.

git replace --graft ${OLD_COMMIT}
git filter-repo --proceed

The git replace --graft command with no parent arguments makes ${OLD_COMMIT} a new root commit.

Restricting to a Range

All filter-repo commands can be restricted to a specific range of commits:

# Single range
git filter-repo ... --refs C..H

# With exclusions
git filter-repo ... --refs C..H ^D

# Alternative range
git filter-repo ... --refs D..H ^C

Use ^C instead of --not C since --not appears to be a flag name which breaks parsing.

Getting Started

Core Concepts

Common Use Cases

Guides

Migration Guides

Examples

Resources

Converting from filter-branch

Converting from BFG Repo Cleaner

Common Operations

Purge a large list of files

Removing a directory

Removing paths with a certain extension

Extract library from subdirectory

Only keep files from specific branches

Replace words in all commit messages

Remove spaces at end of lines

Replace binary blob in history

Renormalize line endings and add .gitattributes

Include and exclude rules

Remove files with backslashes

Convert NFD filenames to NFC

Set committer of last few commits

Handle special characters in names

Add files to root commits

Update submodule hashes

Replace PNGs with compressed versions

Remove commits older than N days

Restricting to a Range

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Common Use Cases

Guides

Migration Guides

Examples

Resources

​Converting from filter-branch

​Converting from BFG Repo Cleaner

​Common Operations

​Purge a large list of files

​Removing a directory

​Removing paths with a certain extension

​Extract library from subdirectory

​Only keep files from specific branches

​Replace words in all commit messages

​Remove spaces at end of lines

​Replace binary blob in history

​Renormalize line endings and add .gitattributes

​Include and exclude rules

​Remove files with backslashes

​Convert NFD filenames to NFC

​Set committer of last few commits

​Handle special characters in names

​Add files to root commits

​Update submodule hashes

​Replace PNGs with compressed versions

​Remove commits older than N days

​Restricting to a Range

Build docs developers (and LLMs) love

Converting from filter-branch

Converting from BFG Repo Cleaner

Common Operations

Purge a large list of files

Removing a directory

Removing paths with a certain extension

Extract library from subdirectory

Only keep files from specific branches

Replace words in all commit messages

Remove spaces at end of lines

Replace binary blob in history

Renormalize line endings and add .gitattributes

Include and exclude rules

Remove files with backslashes

Convert NFD filenames to NFC

Set committer of last few commits

Handle special characters in names

Add files to root commits

Update submodule hashes

Replace PNGs with compressed versions

Remove commits older than N days

Restricting to a Range