Git hash function transition

SHA-256 リポジトリーは、 リポジトリー・フォーマット・バージョン 1 を使用します(gitrepository-layout(5) 参照)。 extensions.objectFormat および extensions.compatObjectFormat (git-config(1) 参照)は以下のとおり設定されます:

core.repositoryFormatVersion=1 の設定と extensions.* の設定の組み合わせにより、v0.99.9l より後のバージョンの Git は SHA-256 リポジトリで操作しようとせずに死んでしまい、代わりにエラーメッセージを出すようになります。

これらのリポジトリ拡張機能の詳細については、以下の「Transition plan」(移行計画)セクションを参照してください。

オブジェクトは、40 桁の 16 進数の SHA-1 名または 64 桁の 16 進数の SHA-256 名、およびそれらから派生した名前で名前を付けることができます (gitrevisions(7) 参照)。

オブジェクトの SHA-1 名は、そのタイプ、長さ、ヌルバイト、およびオブジェクトの SHA-1 コンテンツを連結したものの SHA-1 です。 これは、Git でオブジェクトに名前を付けるために使用される従来の <sha1> です。

オブジェクトの SHA-256 名は、そのタイプ、長さ、ヌルバイト、およびオブジェクトの SHA-256 コンテンツを連結したものの SHA-256 です。

SHA-256名で名付けられたオブジェクトはSHA-256名で他のオブジェクトを参照し、SHA-1名で名付けられたオブジェクトはSHA-1名で他のオブジェクトを参照するので、SHA-1とSHA-256で名付けられた、タグオブジェクトまたはコミットオブジェクトまたはツリーオブジェクトのバイト列としてのコンテンツは異なります。

あるオブジェクトの SHA-256 コンテンツは、あるオブジェクトによって参照されるオブジェクト達が、 SHA-1 名の代わりに SHA-256 名を使用して命名されることを除いて、オブジェクトの SHA-1 コンテンツと同じです。 ブロブオブジェクトは他のオブジェクトを参照しないため、その SHA-1 コンテンツと SHA-256 コンテンツは同一です。

この形式では、SHA-256 コンテンツと SHA-1 コンテンツ間の双方向変換(round-trip conversion)が可能です。

緩いオブジェクト(loose objects)は zlib 圧縮を使用し、パックオブジェクトは gitformat-pack(5) に記載されているパック形式を使用します。 圧縮されて保存されるコンテンツは、SHA-1 コンテンツの代わりに SHA-256 コンテンツを使用します。

パックインデックスファイル(.idx) は、複数のハッシュ関数をサポートする新しい v3 形式を使用します。 その形式は以下のとおりです(すべての整数はネットワークバイトオーダーです):

The "full main hash" is a full-length hash of the main (not compatibility) algorithm in the repository. Thus, if the main algorithm is SHA-256, this is a 32-byte SHA-256 hash and for SHA-1, it’s a 20-byte SHA-1 hash.

新しいファイル $GIT_OBJECT_DIR/loose-object-idx には、すべての緩いオブジェクト(loose objects)に関する情報が含まれています。その形式は以下のとおり

ここで、オブジェクト名は 16 進形式です。 ファイルはソートされません。

緩いオブジェクト・インデックスは、ロック・ファイル $GIT_OBJECT_DIR/loose-object-idx.lock によって並列書き込みから保護されます。 新しい緩いオブジェクト(loose objects)を追加するには:

エントリを削除するには(「git pack-refs」内や「git-prune」内などで):

インデックスファイルは、SHA-1 名と SHA-256 名の間の双方向マッピングをサポートします。 ルックアップは、通常のオブジェクトルックアップと同様に進行します。 たとえば、SHA-1 名を SHA-256 名に変換(convert)するには、以下のようにします:

ステップ(1)は、通常のオブジェクト検索(lookup)と同じ時間がかかります: O(パック数 * log(パックあたりのオブジェクト数)) です。 ステップ(2)は O(緩いオブジェクトの数) 時間かかります。 良好なパフォーマンスを維持するには、緩いオブジェクトの数を低く抑える必要があります。 詳細については、以下の「Loose objects and unreachable objects」(緩いオブジェクトと到達不能オブジェクト)セクションを参照してください。

新しいオブジェクトを作成するすべての操作(「git commit」など) は、新しいオブジェクトを対応するインデックスに追加するため、このマッピングはオブジェクトストア内のすべてのオブジェクトに対して可能です。

オブジェクトのSHA-1コンテンツは、そのSHA-256コンテンツ参照のすべてのSHA-256名を、変換表(translation table)を使用してSHA-1名に変換することで読み取ることができます。

SHA-1ベースのサーバーから取得するには、 SHA-1ベースの表現と SHA-256 ベースの表現をその場で変換する必要があります。

クライアントに存在する ref 広告(advertisement)で指定された SHA-1 は、SHA-256 に変換でき、変換表(translation table)を使用してローカルオブジェクトとして検索(look up)できます。

ネゴシエーションは次のように進行します。 ローカルで生成されたすべての「have」は、サーバーに送信される前に SHA-1 に変換され、サーバーによって言及された SHA-1 は、ローカルで検索(look up)するときに SHA-256 に変換されます。

ネゴシエーション後、サーバーは要求されたオブジェクトを含むパックファイルを送信します。 以下の手順を使用して、パックファイルを SHA-256 形式に変換します:

ステップ 3 では、新しいオブジェクトによって参照されるすべてのオブジェクトが変換表(translation table)にある必要があります。 これが、トポロジ的並べ替えステップ(the topological sort step)が必要な理由です。

最適化として、ステップ 1 で、各オブジェクトがパックファイル参照から解凍させた非ブロブオブジェクトを記述したファイルを作成できます。 これにより、パックファイル内のオブジェクトを再度解凍させることなく、ステップ 2 のトポロジ的並べ替えが可能になります。 オブジェクトは、ステップ 3 で再度解凍する必要があり、合計で 2 回膨らませます。

Step 4 is probably necessary for good read-time performance. "git pack-objects" on the server optimizes the pack file for good data locality (see Documentation/technical/pack-heuristics.adoc).

このプロセスの詳細は変更される可能性があります。 これをうまく機能させるには、ある程度実地で試してみる事が必要です。

プッシュされたオブジェクトによって参照されるオブジェクトはすでに変換表(translation table)にあるため、プッシュはフェッチよりも簡単です。 プッシュされる各オブジェクトの SHA-1 コンテンツは、「Reading an object’s SHA-1 content」(オブジェクトの SHA-1 コンテンツの読み取り)セクションで説明した方法で説明した方法で読み込むと、git send-pack で書かれたパックを生成することができるようになります。

新しいフィールド「gpgsig-sha256」をコミットオブジェクト形式に追加して、 SHA-1 に依存せずにコミットに署名できるようにします。 既存の「gpgsig」フィールドに似ています。 その署名付きペイロードは、「gpgsig」および「gpgsig-sha256」フィールドが削除されたコミットオブジェクトの SHA-256 コンテンツです。

これは、コミットに署名できることを意味します

「git verify-commit」の古いバージョンでは、ケース (1) と (2) の gpgsig 署名を変更せずに検証でき、ケース (3) を通常の署名なしコミットと見なすことができます。

We add new fields "gpgsig" and "gpgsig-sha256" to the tag object format to allow signing tags in both formats. The in-body signature is used for the signature in the current hash algorithm and the header is used for the signature in the other algorithm. Thus, a dual-signature tag will contain both an in-body signature and a gpgsig-sha256 header for the SHA-1 format of an object or both an in-body signature and a gpgsig header for the SHA-256 format of and object.

The signed payload of the tag is the content of the tag in the current algorithm with both its gpgsig and gpgsig-sha256 fields and "-----BEGIN PGP SIGNATURE-----" delimited in-body signature removed.

This means tags can be signed using one or both algorithms.

コミットの SHA-1 コンテンツの mergetag フィールドには、そのコミットによってマージされたタグの SHA-1 コンテンツが含まれます。

同じコミットの SHA-256 コンテンツの mergetag フィールドには、同じタグの SHA-256 コンテンツが含まれています。

記録されたサブモジュールポインターを変換(convert)するには、変換されたサブモジュールリポジトリを配置する必要があります。 サブモジュールの変換表(translation table)を使用して、新しいハッシュを検索(look up)できます。

Loose-object-idx の高速検索(fast lookup)では、緩いオブジェクト(loose objects)の数が増えすぎないようにする必要があります。

「git gc --auto」は現在、6700 個の緩いオブジェクトが存在するようになるまで待ってから、パックファイルに統合します。 私達はこれを使用するためのより適切なしきい値を見つけるために測定を行う必要があります。

「git gc --auto」は現在、50 個のパックが存在するようになるまで待ってから、パックファイルを結合します。 緩いオブジェクトを積極的にパッキングすると、パックファイルの数が急激に増加する可能性があります。 これは、Martin Fick の指数ローリング ガベージ コレクション スクリプト(exponential rolling garbage collection script) (https://gerrit-review.googlesource.com/c/gerrit/+/35215) に似た戦略を使用することで軽減できます。

「git gc」は現在、刈り込み(prune)時の競合(race)を防ぐために。パックファイル内で遭遇(encounter)した到達不可能なオブジェクトを緩いオブジェクト(loose objects)に追い出し(expel)ます(別のプロセスが、削除しようとしているオブジェクト(the about-to-be-deleted object)を参照する新しいオブジェクトを同時に書き込んでいる場合)。 このため、存在する緩いオブジェクトの数が爆発的に増加し、そして、デルタ形式のオブジェクトが独立した緩いオブジェクトに置き換えられるためにディスク領域の使用量が爆発的に増加します。 さらに悪いことに、緩いオブジェクトの競合は依然として存在します。

代わりに、「git gc」は到達不能オブジェクトを UNREACHABLE_GARBAGE としてマークされた新しいパックファイルに移動する必要があります(PSRC フィールドを使用。下記参照)。 削除されようとしている(about-to-be-deleted)オブジェクトを参照する新しいオブジェクトを作成するときの競合(race)を避けるために、新しいオブジェクトを作成するプログラムコードは、新しい非 UNREACHABLE_GARBAGE パック (または緩いオブジェクト) を参照する UNREACHABLE_GARBAGE パックからすべてのオブジェクトをコピーする必要があります。 UNREACHABLE_GARBAGE は、その作成時刻 (ファイルの mtime で示される) が十分前であれば安全に削除できます。

UNREACHABLE_GARBAGE パックの急増を避けるために、特定の状況下でそれらを組み合わせることができます。 gc.garbageTtl が 1 日(one day)よりも長く設定されている場合は、単一暦日(single calendar day)(UTC)以内に作成されたパック達をまとめて結合できます。 結果のパックファイルには、その日の午前 0 時(midnight)より前の mtime が含まれるため、有効な最大 ttl は、garbageTtl + 1 日になります。 gc.garbageTtl が 1 日未満の場合、暦日(calendar day)をその ttl の 3 分の 1 の間隔に分割します。 同じ間隔内で作成されたパック達は、一緒に結合できます。 結果のパックファイルには、間隔の終了前の mtime が含まれるため、有効な最大 ttl は、garbageTtl * 4/3 に等しくなります。

このルールは、Thirumala Reddy Mutchukota の JGit の変更 https://git.eclipse.org/r/90465 に由来します。

UNREACHABLE_GARBAGE 設定は、パックインデックスの PSRC フィールドに入ります。 より一般的には、そのフィールドはパックがどこから来たかを示します。

この情報は、デバッグや、「gc --auto」でどのパックを合体させるかを適切に選択するのに役立ちます。

SHA-1 コンテンツから SHA-256 コンテンツへの変換(conversion)では、元のオブジェクトの破損(brokenness)が保持されます(例えば: 先行 0 でエンコードされたツリーエントリモードや、パスが正しくソートされていないツリーオブジェクトや、作成者またはコミッターなしでオブジェクトをコミットする)。 これは、双方向(round-trip)変換を可能にする設計上の意図的な機能です。

より深刻に壊れたオブジェクト (たとえば、切り捨てられた「ツリー」ヘッダー行を含むコミット) は変換できませんが、なにしろそんなのは現在の Git でも使用できません。

ローカルで生成された変換表(translation table)ですべての参照オブジェクトを使用できるようにする必要があるため、この設計では浅い(shallow)クローンまたはフェッチされていないサブモジュールはサポートされていません。 プロトコルの改善により、この制限を解除できる可能性はあります。

上記と同一の理由により、SHA-256 リポジトリは、objects/info/alternates または $GIT_ALTERNATE_OBJECT_REPOSITORIES を使用して SHA-1 リポジトリからオブジェクトを借用(borrow)することはできません。

「git notes」ツールは、SHA-1 名をキーとしてオブジェクトに注釈を付けます。 この設計では、ノートツリーを移行(migrate)して SHA-256 名を使用する方法については説明していません。 その移行は個別に行われるものと思われます(例えばノートツリーのルートにあるファイルを使用して、どのハッシュを使用するかを記述するなど)。

Git プロトコルが SHA-256 をサポートするまでは、公開されている Git サーバーで SHA-256 ベースのストレージを使用することはかなり非推奨です。 Git プロトコルが SHA-256 のサポートを取得したら、SHA-256 ベースのサーバーは SHA-1 互換性をサポートしない可能性が高くなります。これは、複製中に非常にコストのかかるハッシュの再エンコードを回避し、ピアの最新化を促進するためです。

ここで説明する設計では、個人の SHA-256 リポジトリの SHA-1 クライアントによるフェッチを許可します。これは、そのリポジトリからのプッシュを許可するよりもそれほど難しくないためです。 このサポートは、構成オプションによって保護する必要があります — 多数のクライアントにサービスを提供する git.kernel.org のようなサーバーは、そのコストを負担しないと予想されます。

署名されたコミットとタグの署名されたペイロードは、オブジェクトの識別に使用されるハッシュを明示的に指定しません。 いつか Git が現在の SHA-1 (16 進数 40 桁) または SHA-256 (16 進数 64 桁) オブジェクトと同じ長さの新しいハッシュ関数を採用した場合、オブジェクト署名の PGP 署名ペイロードの背後にある意図は不明瞭になります:

Does this mean Git v2.12.0 is the commit with SHA-1 name e7e07d5a4fcc2a203d9873968ad3e6bd4d7419d7 or the commit with new-40-digit-hash-name e7e07d5a4fcc2a203d9873968ad3e6bd4d7419d7?

幸い、SHA-256 と SHA-1 では長さが異なります。 Git がオブジェクトに名前を付けるために同じ長さの別のハッシュを使用し始めた場合、この問題に対処するには、そのハッシュを使用する署名付きペイロードの形式を変更する必要があります。

移行をサポートするために (下記「Transition plan」(移行計画)参照)、この設計では 4 つの異なる操作モードがサポートされています:

モードは構成で指定されます。

ユーザーは、モードをオーバーライドして、特定のリビジョン指定子(specifier)と出力に使用する形式を明示的に指定することもできます。 例えば:

Linux カーネルのようなプロジェクトは大規模で複雑なため、リポジトリに基づくすべてのプロジェクトのスイッチを一度に切り替えることは不可能です。

すべての開発者と開発者をサポートするサーバーオペレーターが同じ指定日に切り替えなければならないだけでなく、サポートツール (継続的インテグレーション、コードレビュー、バグトラッカーなど) も同様に調整する必要があります。 これにより、多数の人が移行に踏み切る時期が来る前に、一部のプロジェクト参加者のテストから早期にフィードバックを得るというのは難しくなります。

(例: https://lore.kernel.org/git/22708.8913.864049.452252@chiark.greenend.org.uk/ ) 新しく作成されたオブジェクトは新しいハッシュによってアドレス指定されますが、そのようなオブジェクト内(例: コミットオブジェクト)では、まだ古いハッシュ関数を使用してオブジェクトをアドレス指定できます。

SHA-256 コンテンツ ベースの署名のコミットおよびタグオブジェクトに gpgsig-sha256 フィールドを導入する代わりに、この設計の以前のバージョンでは、既存の SHA-1 コンテンツ ベースの署名を強化するために「hash sha256 <SHA-256 name>」フィールドが追加されました。

つまり、単一の署名が、両方のハッシュ関数を使用してオブジェクトのコンテンツを証明するために使用されました。 これにはいくつかの利点がありました:

ただし、欠点もありました:

変換表(translation table)を構築する作業の一部は、プッシュする時まで延期できますが、それはプッシュを非常に複雑にし、遅くします。 オブジェクトの作成時に SHA-1 名を計算すると同時に、オブジェクトがディスクにストリーミングされ、その SHA-256 名が計算されることは、許容できるコストです。