やあ。大規模なモノレポの管理に頭を抱えているエンジニアの皆さん、こんにちは。
「この巨大なリポジトリから、特定のプロジェクトだけを切り出して、履歴も綺麗なまま別のリポジトリに移したい……」
そんな時、昔は `git-filter-branch` を使っていました。しかし、もしあなたが今、それを教本通りに使おうとしているなら、すぐに手を止めてください。それはもう「遺物」です。処理は遅く、履歴を破壊するリスクも高く、何より精神衛生上よくありません。
今日は、現代のDevOpsにおいて「リポジトリの外科手術」を安全かつ爆速で行うための標準ツール、`git-filter-repo` について、その極意を伝授しましょう。これをマスターすれば、リポジトリの断捨離が数分で完了します。
—
1. なぜ git-filter-repo なのか？
`git-filter-branch` は、Gitの内部構造を深く理解していないと「履歴の崩壊」という大惨事を招きかねない諸刃の剣でした。一方で `git-filter-repo` は、最初から「リポジトリの書き換え」を目的に設計されています。
- 圧倒的な速度: Pythonで記述され、内部処理が最適化されているため、数GBのリポジトリでも数分で終わります。
- 安全性: デフォルトで「元のリポジトリを破壊しない」設計になっており、失敗したときの復旧が容易です。
- 直感的なAPI: 複雑なシェルスクリプトを書く必要はもうありません。
—
2. 環境構築：まずはここから
このツールはPython製です。以下のコマンドでインストールしましょう。
Pythonのパッケージマネージャでインストール
pip install git-filter-repo
念のため動作確認
git filter-repo –version
※もし `pip` がない環境なら、単に [公式リポジトリ](https://github.com/newren/git-filter-repo) から `git-filter-repo` スクリプトをダウンロードしてパスを通すだけでも動作します。
—
3. 【実践】特定ディレクトリの抽出・自動化
今回は「巨大なモノレポ `my-monorepo`」の中から、`services/auth-api` というディレクトリだけを抽出して、独立した新しいリポジトリを作るシナリオで解説します。
手順1：リポジトリの複製（ここが重要）
元のリポジトリを汚さないために、必ずクローンしたものに対して作業してください。
1. 抽出対象のクローンを作成
git clone my-monorepo auth-api-project
cd auth-api-project
2. 履歴を維持したまま、特定のディレクトリ以外を削除する
git filter-repo –path services/auth-api/
手順2：ディレクトリ構造の調整
このままだと、新しいリポジトリのルートディレクトリに `services/auth-api/` という階層が残ってしまいます。これをルートに引き上げましょう。
–path-rename を使って、パスをルートへ移動させる
git filter-repo –path-rename services/auth-api/:
これで、`services/auth-api/` 内にあったファイルが、新しいリポジトリの直下に展開されます。これぞ外科手術の醍醐味です。
—
4. 精度高い「HelloWorld」的動作確認
作業が終わったら、以下のチェックポイントで「手術が成功したか」を確認してください。
1. ディレクトリの確認: `ls -la` を叩いて、目的のファイルだけがルートにあるか？
2. 履歴の確認: `git log –oneline` を叩いて、そのディレクトリに関係するコミット履歴だけが正しく残っているか？（他のディレクトリの履歴が混ざっていないか？）
3. 不要なブランチの掃除: `git branch -a` で余計なリモート参照が残っていないか？（`git-filter-repo` は自動でリセットしてくれますが、念のため確認しましょう）
—
5. 先輩エンジニアからのアドバイス：運用上のハック
- 大容量ファイル（LFS/バイナリ）の削除:
もしリポジトリのサイズを劇的に減らしたいなら、`–strip-blobs-bigger-than 10M` のようなオプションを追加するだけで、10MB以上の巨大ファイルを履歴から一掃できます。これだけでCIのビルド時間が数分短縮されることもあります。
- チームへの共有:
履歴を書き換えることは「歴史の改ざん」です。チームメンバー全員がそのリポジトリのクローンを捨て、新しいリポジトリを `git clone` し直すという合意形成だけは、技術以上に大切にしてください。
—
まとめ
`git-filter-repo` を使えば、モノレポからの切り出しは「恐怖を伴う複雑な作業」から「数分で終わるルーチンワーク」に変わります。
最初は緊張するかもしれませんが、クローンさえあれば何度でもやり直せるのがGitの素晴らしいところです。まずは実験用の適当なリポジトリで試してみてください。
「リポジトリは生き物であり、整理整頓こそが最大の最適化である」
この言葉を胸に、ぜひあなたの開発環境をクリーンに保ってください。応援していますよ！