Gitリポジトリの履歴を迅速に書き換える
Quickly rewrite Git repository history (github.com)
要約
git-filter-repoは、履歴を書き換えるための多機能ツールであり、他の場所では見つけられない機能も備えています。これはgit filter-branchと同様の領域に位置しますが、パフォーマンスの悪さがなく、より多くの機能と、些細な書き換えケースを超えて使いやすさがスケールする設計を備えています。gitプロジェクトは現在、git filter-branchの代わりにgit-filter-repoを推奨しています。ほとんどのユーザーはfilter-repoをシンプルなコマンドラインツールとして使用するでしょうが、その中核には履歴書き換えツールを作成するためのライブラリが含まれています。
全文翻訳
Gitリポジトリ履歴を素早く書き換える
git filter-repo は、履歴を書き換えるための多機能ツールであり、他のツールには見られない機能 を備えています。これは、git filter-branch と同じ領域のツールですが、パフォーマンス の悪さ、より多くの機能、そして単純な書き換えケースを超えた使いやすさの設計という点で優れています。git filter-repo は現在、git プロジェクトによって git filter-branch の代わりに推奨されています。
ほとんどのユーザーは filter-repo を単純なコマンドラインツールとして使用するでしょうが(おそらく数個のフラグしか使わないでしょう)、その中核には履歴書き換えツールを作成するためのライブラリが含まれています。そのため、特殊なニーズを持つユーザーは、これを利用して完全に新しい履歴書き換えツールを迅速に作成 できます。
目次
- 前提条件
- インストール方法は?
- 使い方は?
- なぜ他の代替手段ではなく filter-repo なのか?
- 簡単な例と比較
- filter-repo の設計思想
- 貢献方法は?
- 行動規範はありますか?
- アップストリームの改善
前提条件
filter-repo には以下が必要です:
- git >= 2.36.0
- python3 >= 3.6
インストール方法は?
git-filter-repo リポジトリには多くのファイルがありますが、主要なロジックはすべて git-filter-repo という単一ファイルの Python スクリプトに含まれています。これにより、多くのシステムで基本的な使用のためのインストールが非常に簡単になります。そのファイルを $PATH に配置するだけです。
基本的な使用法や特別なケース以外の詳細については、INSTALL.md を参照してください。より詳細な手順が必要なのは、以下のいずれかに該当する場合のみです:
- 上記の簡単なインストールのコメントが直感的に理解できない場合
- "python3" 以外の名前の python3 実行ファイルを使用している場合
- ドキュメント(-h で表示される組み込みドキュメント以外)をインストールしたい場合
- contrib の例の一部を実行したい場合
- filter-repo をモジュール/ライブラリとして使用して、独自の Python フィルタリングスクリプトを作成したい場合
使い方は?
包括的なドキュメントについては:
- ユーザーマニュアル を参照してください
- htmlpreview.github.io のレイアウトが気に入らない場合は、さまざまな外部サイトでユーザーマニュアルの代替フォーマットが利用可能です(例)。ただし、最新リリース時点での情報のみである可能性があります。
例から学ぶことを好む場合:
- filter-branch コマンドからの変換チートシート があり、filter-branch のマニュアルのすべての例をカバーしています。
- BFG Repo Cleaner コマンドからの変換チートシート があり、BFG のウェブサイトのすべての例をカバーしています。
- 簡単な例 が参考になるかもしれません。
- ユーザーマニュアルには、包括的な例のセクション があります。
- ユーザーから報告された問題に基づいた例のフィルタリング集 を収集しました。
いずれの場合も、よくある質問 も役立つでしょう。
なぜ他の代替手段ではなく filter-repo なのか?
これは Git Rev News の記事で より詳細にカバーされていますが、主な競合他社に関するハイライトをいくつか紹介します:
filter-branch
-
filter-branch は、非自明なリポジトリでは極端に遅い、あるいは使用不能なほど遅い です(本来あるべき速度の数倍遅い)。
-
filter-branch は多くの落とし穴があり、書き換えを静かに破損させるか、少なくとも開始時よりも問題が多く厄介なものにして「クリーンアップ」の努力を妨げる可能性があります。
-
filter-branch は、少しでも非自明な書き換えを行うには使用が非常に面倒です (例)。
-
git プロジェクトは、filter-branch の上記の問題は後方互換性を保って修正できないと述べており、filter-branch の使用を中止することを推奨しています。
-
filter-branch の熱狂的なファンは、filter-lamely(別名 filter-branch-ish)に興味を持つかもしれません。これは filter-repo をベースにした filter-branch の再実装であり、より高速ですが、filter-repo ほど速くも安全でもありません。
-
マニュアルの例コマンドを filter-repo コマンドに変換する方法を示すチートシート が利用可能です。
BFG Repo Cleaner
-
当時の優れたツールでしたが、一部の操作は簡単にするものの、書き換えの種類は限られています。
-
そのアーキテクチャは、より多くの種類の書き換えを処理するのに適していません。
-
そのアーキテクチャは、意図されたユースケースにおいても、いくつかの欠点やバグを抱えています。
-
bfg のファンは、bfg-ish に興味を持つかもしれません。これは filter-repo をベースにした bfg の再実装であり、bfg に比べていくつかの新機能やバグ修正が含まれています。
-
BFG Repo Cleaner のマニュアルの例コマンドを filter-repo コマンドに変換する方法を示すチートシート が利用可能です。
簡単な例と比較
リポジトリの一部を抽出し、その一部だけを別の大きなリポジトリにマージしたいとしましょう。抽出にあたっては、以下を行いたいとします:
- 単一のディレクトリ
src/の履歴を抽出します。つまり、リポジトリに残るのはsrc/以下のパスのみとなり、このディレクトリ以外のパスのみを変更したコミットは削除されます。 - すべてのファイルを
my-module/という新しい先頭ディレクトリを持つようにリネームします(例:src/foo.cがmy-module/src/foo.cになる)。 - 抽出されたリポジトリ内のすべてのタグに
my-module-というプレフィックスを付けます(後でこのリポジトリを別のものにマージする際に競合を避けるため)。
filter-repo での解決策
これを filter-repo で行うのは、次のコマンドと同じくらい簡単です:
git filter-repo --path src/ --to-subdirectory-filter my-module --tag-rename '':'my-module-'
(単一引用符は必須ではありませんが、空文字列を my-module- というプレフィックスに置き換えていることを人間が理解しやすくします。)
BFG Repo Cleaner での解決策
BFG Repo Cleaner はこの種の書き換えを行う能力がありません。実際、要求された 3 つの変更すべてがその能力の範囲外です。
filter-branch での解決策
filter-branch は、必要な呼び出し方法を理解した後でも、多くの注意点(詳細は後述)を伴います:
git filter-branch \
--tree-filter 'mkdir -p my-module && \
git ls-files \
| grep -v ^src/ \
| xargs git rm -f -q && \
ls -d * \
| grep -v my-module \
| xargs -I files mv files my-module/' \
--tag-name-filter 'echo "my-module-$(cat)"' \
--prune-empty -- --all
git clone file://$(pwd) newcopy
cd newcopy
git for-each-ref --format="delete %(refname)" refs/tags/ \
| grep -v refs/tags/my-module- \
| git update-ref --stdin
git gc --prune=now
上記の filter-branch 呼び出しが --tree-filter を使用しているため非常に遅くなることに気づく人もいるかもしれません。代わりに --index-filter オプションを使用することもできます。上記のコマンドを次のように変更します:
git filter-branch \
--index-filter 'git ls-files \
| grep -v ^src/ \
| xargs git rm -q --cached;
git ls-files -s \
| sed "s%$(printf \t)%&my-module/%";
git ls-files \
| grep -v ^my-module/ \
| xargs git rm -q --cached' \
--tag-name-filter 'echo "my-module-$(cat)"' \
--prune-empty -- --all
git clone file://$(pwd) newcopy
cd newcopy
git for-each-ref --format="delete %(refname)" refs/tags/ \
| grep -v refs/tags/my-module- \
| git update-ref --stdin
git gc --prune=now
しかし、どちらの filter-branch コマンドにも多くの注意点があります。まず、なぜここで 5 つのコマンドをリストアップしているのか疑問に思うかもしれません。--all と --tag-name-filter を使用し、filter-branch のマニュアルがクローンで古いオブジェクトを削除するのに十分だと主張しているにもかかわらず、他のタグを削除し、別の gc を実行してプッシュする前に新しい履歴と古い履歴が混在するのを避けるために、古いオブジェクトをクリーンアウトする追加の手順が still 必要です。その他の注意点:
- コミットメッセージは書き換えられません。そのため、一部のコミットメッセージが(省略された)SHA1 で以前のコミットを参照している場合、書き換え後、それらのメッセージは存在しないコミットを参照するようになります。それらの(省略された)SHA1 参照を新しいコミット ID を参照するように書き換う方が良いでしょう。
--prune-emptyフラグは、削除されるべきコミットを見逃すことがあり、また、フィルタリングの結果として空になったコミットだけでなく、元々空だった コミットも削除してしまいます。バージョン管理や公開目的で意図的に空のコミットを使用しているリポジトリの場合、これは有害になる可能性があります。- 上記のコマンドは OS 固有です。
sed、xargsなどにおける GNU と BSD の問題は、ユーザーをしばしばつまずかせます。私は、filter-branchのマニュアルにある唯一の例が、それを両方使用し、サブディレクトリへのすべて移動方法を示しているのが Linux 固有であり、移植性の問題が読者に明らかではないため、ほとんどの人が--index-filterを使用するのを失敗したと思います。それは、大きな失敗ではなく、静かに誤動作するためです。 --index-filterバージョンのfilter-branchコマンドは--tree-filterバージョンよりも 2~3 倍高速かもしれませんが、どちらのfilter-branchコマンドも、filter-repo よりも桁違いに遅くなります。- 両方のコマンドは、すべてのファイル名が ASCII 文字のみで構成されていると仮定しています(タブや二重引用符のような特殊な ASCII 文字でさえ、混乱を引き起こし、ファイルが見つからなかったり、ファイル名が間違っていたりする可能性があります)。
fast-export/fast-import での解決策
次のようなもので、これを何とかハックすることができます:
git fast-export --no-data --reencode=yes --mark-tags --fake-missing-tagger \
--signed-tags=strip --tag-of-filtered-object=rewrite --all \
| grep -vP '^M [0-9]+ [0-9a-f]+ (?!src/)' \
| grep -vP '^D (?!src/)' \
| perl -pe 's%^(M [0-9]+ [0-9a-f]+ )(.*)$%\1my-module/\2%' \
| perl -pe 's%^(D )(.*)$%\1my-module/\2%' \
| perl -pe s%refs/tags/%refs/tags/my-module-% \
| git -c core.ignorecase=false fast-import --date-format=raw-permissive \
--force --quiet
git for-each-ref --format="delete %(refname)" refs/tags/ \
| grep -v refs/tags/my-module- \
| git update-ref --stdin
git reset --hard
git reflog expire --expire=now --all
git gc --prune=now
しかし、これにはいくつかの厄介な注意点と制限があります:
- 様々な
grepと正規表現の置換は、fast-exportストリーム全体に対して操作されるため、コミットメッセージのような意図しない部分を誤って破損させる可能性があります。ファイルの内容を編集する必要があり--no-dataフラグを外した場合、ファイルの内容も破損させる可能性があります。 - このコマンドは、リポジトリ内のすべてのファイル名が ASCII 文字のみで構成されており、タブや二重引用符のような特殊文字を除外していると仮定しています。そのような特殊なファイル名が古い
src/ディレクトリ内に存在する場合、保持される意図があったにもかかわらず削除されてしまいます。(わずかに異なるリポジトリの書き換えでは、この種の編集は、ファイル名の末尾近くや先頭のディレクトリ名に余分な二重引用符を追加することで、特殊文字を含むファイル名を破損させるリスクもあります。) - このコマンドは、大量の無用な空のコミットを残し、それらを削除する現実的な方法がありません。(そして、この手法を別のツールと組み合わせて空のコミットを削除しようとした場合、フィルタリングによって空になったコミットと、フィルタリング前に空だったため保持したい可能性のあるコミットとを区別する方法がなくなります。)
- 他のコミットをハッシュで参照するコミットメッセージは、もはや存在しない古いコミットを参照するようになります。コミットメッセージを編集して更新しようとすることは、この種の直接的な書き換えに追加するのが非常に困難です。
filter-repo の設計思想
既存のリポジトリフィルタリングツールのいずれも、私が望むことをしてくれませんでした。それらはすべて私のニーズを満たしていませんでした。どのツールも、最初の 8 つの特性のうちのいずれも提供しておらず、最後の 4 つの特性のうちの 2 つ以上を提供しているものはありませんでした:
-
[レポート開始] ユーザーが推測したり、それを理解するために他のツールを見つけたりすることを期待するのではなく、ユーザーが何を削除またはリネームするかを始めるのに役立つリポジトリの分析を提供します。(例:特別なフラグ、例えば
--analyzeを付けて初めて実行することでトリガーされます。) -
[保持 vs 削除] ユーザーが選択したパスを簡単に削除する方法を提供するだけでなく、ユーザーが特定のパスのみを保持するためのフラグも提供します。もちろん、ユーザーは保持したいパス以外のすべてのパスを削除するように指定することで回避できますが、リポジトリのどのバージョンにも常に存在したすべてのパスを指定する必要があることは、時には非常に困難になる可能性があります。filter-branch では、
git ls-files | grep -v ... | xargs -r git rmのようなパイプラインを使用するのが妥当な回避策かもしれませんが、扱いにくく、ユーザーにとってそれほど直接的ではありません。さらに、それらのコマンドは OS 固有であることがよくあります(提供したスニペットで GNU 拡張を見つけられますか?)。 -
[リネーム] パスをリネームするのは簡単であるべきです。例えば、あるサブディレクトリをリポジトリのルートとして扱うことを許可するだけでなく、リポジトリのルートを単なるサブディレクトリにするオプションをユーザーに提供すること。そしてより一般的に、ファイルやディレクトリを簡単にリネームできるようにすること。リネームによって複数のファイルが同じパスに存在する場合に、健全性チェックを追加します。(そして、コミットが単に
oldname->newnameを変更なしでコピーした場合、oldname->newnameのフィルタリングが健全性チェックをトリガーしてそのコミットで失敗しないように特別な処理を追加します。) -
[よりインテリジェントな安全性] リポジトリ内の特別な名前空間に元の参照のコピーを書き出すことは、ユーザーフレンドリーな回復メカニズムを提供しません。多くの人はそれを使って回復するのに苦労するでしょう。リポジトリのフィルタリング操作を行ったほとんどすべての人が、新しいクローンで行っています。なぜなら、エラーが発生した場合にクローンをワイプアウトする方が、回復メカニズムよりもはるかに簡単だからです。このワークフローを、新しいクローンでない場合に検出して中止する ことで強く推奨します。ただし、ユーザーが
--forceで上書きしない限りです。 -
[自動縮小] フィルタリング後に古いゴミを自動的に削除し、リポジトリを再パックします(オーバーライドされない限り)。これにより、ユーザーの作業が簡略化され、古い履歴と新しい履歴が混在するのを防ぎ、マニュアルに記載されているリポジトリを縮小する多段階プロセスが一部のケースで実際には機能しないという問題を回避できます。(filter-branch のことですよ。)
-
[クリーンな分離] 古いリポジトリと書き換えられたリポジトリが混在することによるユーザーの混乱(古いものを誤って再プッシュしてしまうこと)を防ぎます。(これは、
--tag-name-filterオプションを使用する場合、特に filter-branch で問題となり、また、一部のブランチのみをフィルタリングする場合にも問題となることがあります。) -
[汎用性] ユーザーにツールを拡張したり、既存の機能を利用して新しいツールを作成したりする能力を提供し、この拡張性を(a)別プロセスをフォークする必要がない(パフォーマンスを損なう)、(b)ユーザーが OS 依存のシェルコマンドを指定する必要がない(コマンドを共有できなくなる)、(c)リッチなデータ構造を活用できる(ハッシュ、辞書、リスト、配列はシェルでは非常に困難)、(d)妥当な文字列操作機能を提供する(シェルでは著しく不足している)方法で提供します。
-
[古いコミット参照] ユーザーが古いコミット ID を新しいリポジトリで使用できる方法を提供します(特に、
refs/replace/参照を使用して古いハッシュから新しいハッシュへのマッピングを通じて)。 -
[コミットメッセージの一貫性] コミットメッセージが ID で他のコミットを参照している場合(例:「これはコミット 01234567890abcdef を元に戻します」、「コミット 0013deadbeef9a... では」)、それらのコミットメッセージは新しいコミット ID を参照するように書き換えられるべきです。
-
[空になるコミットの削除] フィルタリングによって空になったコミットは削除されるべきです。コミットの親が削除された場合、最初の削除されていない祖先が新しい親になります。削除されていない祖先が存在せず、コミットがマージでなかった場合、それは新しいルートコミットになります。削除されていない祖先が存在せず、コミットがマージだった場合、マージは親を 1 つ少なくなり(これにより、それ自体がファイル変更がない場合に削除される非マージコミットになる可能性が高くなります)。ここで注意すべき特別な点は、空になったコミットを削除するのであって、元々空だった コミットを削除するのではないということです。一部のプロジェクトは、バージョン管理や公開の目的で意図的に空のコミットを作成しており、これらは削除されるべきではありません。(特別なケースとして、元々空だったが親が削除されたコミットも「空になった」と見なされます。)
-
[非正規形になるコミットの削除] 空になるコミットの削除は、トポロジーの変更を引き起こす可能性があり、多くの特別なケースがあります。通常、マージコミットはグラフのトポロジーを維持するために必要なので削除されませんが、親や他の祖先の削除は最終的に 1 つ以上の親の喪失につながる可能性があります。単純なケースはすでに上で述べました:マージコミットが十分な親を失って非マージコミットになり、ファイル変更がない場合、それも削除される可能性があります。マージコミットは非正規形になるトポロジーを持つこともあります:マージベースが両方の親になる(元のリポジトリからのすべての介在コミットが削除された場合)、または一方の親がもう一方の親の祖先になるという状況になる可能性があります。そのような場合、マージにファイル変更がない場合、マージコミットも削除される可能性があります。しかし、空のコミットの削除と同様に、元々非正規形だったマージコミット(意図的であった可能性を示す、例:
--no-ffマージ)は削除せず、非正規形になり、かつファイル変更がないマージコミットのみを削除します。 -
[速度] フィルタリングは reasonably fast であるべきです。
貢献方法は?
貢献ガイドライン を参照してください。
行動規範はありますか?
filter-repo コミュニティの参加者は、git プロジェクトと同じ基準を遵守することが期待されています。そのため、git 行動規範 が適用されます。
アップストリームの改善
filter-repo およびその前身 に対する作業は、filter-repo がその作業を行うために必要なことから、コア git における fast-export および fast-import(および時折他のコマンド)の数多くの改善も推進してきました:
- git-2.48.0
- git-2.28.0
- git-2.24.0
- fast-export: ネストされたタグを処理
- t9350: コミット以外のものをタグ付けするテストを追加
- fast-export: ユーザーが --mark-tags でタグを要求できるようにする
- fast-export: --import-marks-if-exists のサポートを追加
- fast-import: 新しい 'alias' コマンドのサポートを追加
- fast-import: タグをマークラベルで識別できるようにする
- fast-import: 削除されたタグの処理を修正
- fast-export: タグのみのエクスポートを修正
- git-fast-import.txt: 複数のマージコミットが許可されることを明確にする
- git-2.23.0
- git-2.22.0
- git-2.21.0
- fast-export: sha1 を oid に変換
- git-fast-import.txt: --quiet オプションのドキュメントを修正
- git-fast-export.txt: rev-list 引数に関する誤解を招くドキュメントを明確にする
- fast-export: 正しい enum の値を使用する
- fast-export: パスによるフィルタリングと古いタグが存在する場合にクラッシュするのを回避する
- fast-export: コミット書き換えロジックを再利用のために関数に移動する
- fast-export: パスを使用する場合、存在しないマークでストリームを破損するのを回避する
- fast-export: 要求された ref をエクスポートすることを保証する
- fast-export: --reference-excluded-parents オプションを追加
- fast-import: 保守されていない重複ドキュメントを削除する
- fast-export: --show-original-ids オプションを追加して元の名前を表示する
- git-show-ref.txt: フラグの順序を修正
- git-2.20.0
- git-1.7.3
- git-1.6.4:
- fast-export: setup_revisions を呼び出す前に revs.topo_order を設定する
- fast-export: ツリーをタグ付けするタグを省略する
- fast-export: (null) の代わりに実際の ref 名を表示することを保証する
- fast-export: 関連コミットのドロップを回避するために親の書き換えを行う
- fast-export: 新しくぶら下がったタグのための --tag-of-filtered-object オプションを追加
- 新しい fast-export テストケースを追加
- fast-export: git-rev-list 引数が受け入れられるという事実を文書化する
- git-1.6.3:
- git-1.6.1.4: