Git filter-repo 既にコミットしてしまった不要ファイルを履歴から消す方法

Gitでうっかり大容量のファイルや本来コミットしたくなかったファイルを登録してしまった…。

• ビルド結果やキャッシュが混ざっていた
• 100MBを超えるファイルをPushしようとしてGitHubに拒否された（今回の私）
• セキュリティ上問題のあるファイル（APIキーや秘密情報）を誤ってコミット

こうしたファイルは、単に .gitignore を修正して git rm –cached しても、過去のコミット履歴に残り続けます。

今回は git filter-repo（旧 git filter-branch の後継ツール）の紹介です。過去コミットも含めて不要ファイルを完全削除し、リポジトリを“きれい”に書き換えてしまうことができます。

注意点

• 履歴を改変すると、既存のブランチと互換性がなくなるため、他の開発者と共有している場合は要注意。

• もし既にGitHub等にPushしていたら、force push（–force）でリポジトリを上書きしなければなりません。

• 作業前にバックアップを取っておくことを強く推奨します。

やり方

手順1: git filter-repo をインストール

macOS

brew install git-filter-repo

Windows / Linux

• git-filter-repo公式GitHubページ からスクリプトをダウンロードしてパスに配置、あるいはパッケージマネージャ等でインストール。

インストールできたら git filter-repo –help が実行できるか確認してみましょう。

手順2: 不要ファイルを削除する

2-1. 例: 特定のファイルを削除

git filter-repo --path path/to/your_file.ext --invert-paths

• –path: 削除（除外）したいファイルパス

• –invert-paths: 指定したパスを履歴ごと消すオプション

これで過去のコミットからも your_file.ext が完全に消え、存在しなかったことになります。

2-2. ディレクトリごと削除

git filter-repo --path path/to/unwanted_folder --invert-paths

• unwanted_folder 以下のファイルすべてが対象。

2-3. 複数のパスを一度に削除

git filter-repo \
 --path path/to/big_file_1 \
 --path path/to/big_file_2 \
 --invert-paths

改行やバックスラッシュで続けて書けば、複数ファイル・フォルダをまとめて消せます。

手順3: ローカル確認 & force push

filter-repo の実行が終わると、履歴を書き換えた状態がローカルに反映されます。

変更をリモートに反映するには、通常は強制プッシュが必要です。

git push origin main --force

• これでリモート側も「不要ファイルが含まれていない」新しい履歴に上書きされます。

• コラボレーターがいる場合は衝突や再クローンなどが必要になってくるので、事前に相談してください。

サイズで一括削除する

「50MBを超えるファイルをすべて消す」といった雑なやり方をしたい場合は、以下のようなコマンドも便利です。

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

これで50MBを超えるファイルは履歴から抹消されます。

ただし、どのファイルが削除対象になったかを確認してからにするのがおすすめです。