git-fast-import(1) Manual Page

フロントエンドのデバッグを支援するために、fast-importは、 # (ASCII シャープ/ハッシュ) で始まり、LF で終わる行を無視します。 コメント行には、LFを含まないバイトのシーケンスを含めることができるため、フロントエンドに固有でfast-importのデータストリームを検査するときに役立つ詳細なデバッグ情報を含めるために使用できます。

以下の日付形式がサポートされています。 フロントエンドは、--date-format=<fmt> コマンドラインオプションで形式名を渡すことにより、このインポートに使用する形式を選択する必要があります。

fast-importは、現在のリポジトリを更新し、現在のインポートプロセスを制御するためのいくつかのコマンドを受け入れます。 各コマンドの詳細(例を含む)については後述します。

新しいコミットでブランチを作成または更新し、プロジェクトへの1つの論理的な変更を記録します。

ここで、 <ref> はコミットを行うブランチの名前です。 通常、Gitではブランチ名の前に refs/heads/ が付いているため、CVSブランチシンボル RELENG-1_0 をインポートすると、 <ref> の値に refs/heads/RELENG-1_0 が使用されます。 <ref> の値は、Gitで有効なrefnameである必要があります。 LF はGit refnameでは無効であるため、ここではクォートやエスケープ構文はサポートされていません。

mark コマンドがオプションで表示され、フロントエンドで将来使用するために新しく作成されたコミットへの参照を保存するようにfast-importを要求する場合があります(形式については以下を参照)。 フロントエンドが作成するすべてのコミットにマークを付けることは非常に一般的であり、これにより、インポートされたコミットから将来のブランチを作成できます。

committer に続く data コマンドは、コミットメッセージを提供する必要があります(data コマンドの構文については以下を参照してください)。 空のコミットメッセージをインポートするには、長さ0のデータを使用します。 コミットメッセージは自由形式であり、Gitによって解釈されません。 fast-importでは他のエンコードを指定できないため、現在はUTF-8でエンコードする必要があります。

コミットを作成する前にブランチの内容を更新するために、0個以上の filemodify 、 filedelete 、 filecopy 、 filerename 、 filedeleteall 、 notemodify コマンドを含めることができます。 これらのコマンドは、任意の順序で指定できます。 ただし、 filedeleteall はブランチをクリーンにワイプするため、 filedeleteall コマンドを同じコミット内のすべての filemodify 、 filecopy 、 filerename 、 ` notemodify` コマンドの前に置くことをお勧めします(下記参照)。

コマンドの後の LF はオプションです(以前は必須でした)。 下位互換性の理由から、コミットが data コマンドで終了する場合(つまり、 from 、 merge 、 filemodify 、 filedelete 、 filecopy 、 filerename 、 filedeleteall 、 notemodify コマンドがないことに注意してください)の場合、コマンドの最後に1つではなく2つの LF コマンドが表示される場合があります。

fast-import を使って現在のオブジェクトへの参照を保存し、 フロントエンドが SHA-1 を知らなくても、 将来の時点でこのオブジェクトを呼び出すことができるようにします。 ここで、 現在のオブジェクトは、 mark コマンドが含まれるオブジェクト作成コマンドです。 これは commit や tag や blob にすることができますが、 commit が最も一般的な使用法です。

ここで、 <idnum> は、フロントエンドによってこのマークに割り当てられた番号です。 <idnum> の値は、ASCIIの10進整数として表されます。 値0は予約されており、マークとして使用することはできません。 1以上の値のみをマークとして使用できます。

新しいマークは自動的に作成されます。 同じ <idnum> を別の mark コマンドで再利用するだけで、既存のマークを別のオブジェクトに移動できます。

元のソース管理システムのオブジェクトの名前を提供します。 fast-import はこのディレクティブを単に無視しますが、fast-importにフィードする前にストリームを操作および変更するフィルタープロセスは、この情報を使用する場合があります。

ここで、 <object-identifier> は LF を含まない任意の文字列です。

特定のコミットを参照する注釈付きタグ(annotated tag)を作成します。 軽量(注釈なし)タグ(lightweight tag)を作成するには、下記 reset コマンドを参照してください。

ここで、 <name> は作成するタグの名前です。

タグ名はGitに保存されるときに自動的に refs/tags/ のプレフィックスが付けられるため、CVSブランチシンボル RELENG-1_0-FINAL をインポートすると、 <name> に RELENG-1_0-FINAL だけが使用され、 fast-importは対応するrefを refs/tags/RELENG-1_0-FINAL として書き込みます。

<name> の値は、Gitで有効なrefnameである必要があるため、スラッシュを含めることができます。 LF はGit refnameでは無効であるため、ここではクォートやエスケープ構文はサポートされていません。

from コマンドは commit コマンドと同じです。 詳細については、上記を参照してください。

tagger コマンドは、 commit 内の committer と同じ形式を使用します。 詳細については、再度上記を参照してください。

tagger に続く data コマンドは、注釈付きのタグメッセージを提供する必要があります(data コマンドの構文については以下を参照してください)。 空のタグメッセージをインポートするには、長さ0のデータを使用します。 タグメッセージは自由形式であり、Gitによって解釈されません。 fast-importでは他のエンコードを指定できないため、現在はUTF-8でエンコードする必要があります。

fast-import内からのインポート中に注釈付きタグに署名することはサポートされていません。 フロントエンドは通常そのような署名に入るバイトの完全なセットに(簡単に)アクセスできないため、独自の PGP/GPG 署名を含めることはお勧めしません。 署名が必要な場合は、 reset を使用してfast-import内から軽量タグを作成し、標準の git tag プロセスを使用してそれらのタグの注釈付きバージョンをオフラインで作成します。

名前付きブランチを作成(または再作成)します。オプションで、特定のリビジョンから開始します。 resetコマンドを使用すると、フロントエンドは既存のブランチに対して新しい from コマンドを発行したり、新しいコミットを作成せずに既存のコミットから新しいブランチを作成したりできます。

<ref> と <commit-ish> の詳細については、上記 commit と from を参照してください。

コマンドの後の LF はオプションです(以前は必須でした)。

reset コマンドを使用して、軽量(注釈なし)タグ(lightweight tag)を作成することもできます。 例えば:

これはコミットマーク :938 が参照するものを参照して、軽量タグ refs/tags/938 を作成します。

パックファイルに1つのファイルリビジョンを書き込むように要求します。 リビジョンはコミットに接続されていません。 この接続は、割り当てられたマークを介してブロブを参照することにより、後続の commit コマンドで形成する必要があります。

一部のフロントエンドが独自にブロブの Git SHA-1 を生成し、それを直接 commit にフィードすることを選択したため、ここでは mark コマンドはオプションです。 ただし、マークは安価で保管しやすく、使い勝手も良いため、これは一般的にはマークより手間がかかると思われます。

生データ(ブロブやファイルの内容や、 コミット・メッセージや、 注釈付きタグ・メッセージとして使用するため)を fast-import に提供します。 データは、正確なバイト・カウントを使用して提供することも、 終了行で区切ることもできます。 本番品質の変換を目的とした実際のフロントエンドは、より堅牢で高いパフォーマンスのために、 常に正確なバイト・カウント形式を使用すべきです。 区切り形式(delimited format)は、 主に fast-import のテストを目的としています。

data コマンドの <raw> 部分に表示されるコメント行は、常にデータの本文の一部と見なされるため、fast-importによって無視されることはありません。 これにより、行が # で始まる可能性のある ファイル/メッセージ コンテンツを安全にインポートできます。

最初に新しいオブジェクトを作成せずに、マークが特定のオブジェクトを参照していることを記録します。

<commit-ish> の詳細については、上記の from を参照してください。

fast-importを強制して、現在のパックファイルを閉じ、新しいパックファイルを開始し、現在のすべてのブランチ参照とタグとマークを保存します。

注意: fast-importは、現在のパックファイルが --max-pack-size または 4 GiB のいずれか小さい方の制限に達すると、パックファイルを自動的に切り替えることに注意してください。 自動パックファイル切り替え中、fast-importは、ブランチの参照またはタグまたはマーク を更新しません。

checkpoint はかなりのCPU時間とディスクI/Oを必要とする可能性があるため(パック全体のSHA-1チェックサムを計算し、対応するインデックスファイルを生成し、refを更新するため)、単一の checkpoint コマンド完了に数分かかる場合があります。

フロントエンドは、非常に大規模で長時間実行されるインポート中、または別のGitプロセスにブランチへのアクセスを許可する必要があるときにチェックポイントを発行することを選択できます。 ただし、30 GiB Subversion リポジトリを fast-import によって約3時間でGitにロードできることを考えると、明示的なチェックポイントは必要ない場合があります。

コマンドの後の LF はオプションです(以前は必須でした)。

コマンドが入力ストリームから処理されるときに、 fast-import は progress 行全体を変更せずに、 標準の出力チャネル(ファイルデスクリプタ 1)に出力します。 このコマンドは、それ以外の、 現在のインポートや fast-import の内部状態には影響を与えません。

コマンドの <any> 部分には、 LF を含まないバイトシーケンスを含めることができます。 コマンドの後の LF はオプションです。 呼び出し元は、sedなどのツールを使用して出力を処理し、行の先頭部分を削除したい場合があるかもしれません。以下に例を示します:

checkpoint の直後に progress コマンドを配置すると、 checkpoint が完了したときにリーダーに通知され、 fast-import で更新された ref に安全にアクセスできます。

fast-importが、標準出力または --cat-blob-fd 引数であらかじめ指定されたファイルディスクリプタに、マークに対応するSHA-1を表示するようにします。 このコマンドは、 それ以外の影響をインポートに与えません。 その目的は、 後でコミットがコミット・メッセージで参照する可能性のある SHA-1 達を取得することです。

この出力を安全に読み取る方法の詳細については、以下の「Responses To Commands」(コマンドへの応答)を参照してください。

fast-import により、以前に --cat-blob-fd 引数で設定されたファイル・デスクリプターにブロブが出力されます。 このコマンドは、 それ以外の影響を現在のインポートに与えません。 その主な目的は、 fast-import のメモリにある可能性があるが、 ターゲット・リポジトリーからはアクセスできないブロブを取得することです。

<dataref> は、以前に設定されたマーク参照(:<idnum>)か、既存または書き込みの準備ができているGitブロブの完全な40バイトのSHA-1のいずれかです。

出力は git cat-file --batch と同一形式を使用します:

このコマンドは、 filemodify ディレクティブを表示できる場所で使用でき、コミットの途中で使用できます。 インラインディレクティブを使用する filemodify の場合、 data ディレクティブの直前に表示することもできます。

この出力を安全に読み取る方法の詳細については、以下の「Responses To Commands」(コマンドへの応答)を参照してください。

パスにあるオブジェクトに関する情報を、事前に --cat-blob-fd 引数で指定したファイルディスクリプタへ出力します。 これにより、アクティブなコミットからブロブを表示したり(cat-blob を使用)、以前のコミットからブロブやツリーをコピーして現在のコミットで使用したり(filemodify を使用))することができます。

ls コマンドは、 filemodify ディレクティブを表示できる場所でも使用でき、コミットの途中で使用できます。

<path> の詳細な説明については、上記の filemodify を参照してください。

出力は git ls-tree <tree> -- <path> と同一形式を使用します:

<dataref>は、<path>にあるblob、tree、またはcommitオブジェクトを表し、後の get-mark 、 cat-blob 、 filemodify 、 ls コマンドで使用できます。

そのパスにファイルまたはサブツリーがない場合、 git fast-import が代わりに報告します

この出力を安全に読み取る方法の詳細については、以下の「Responses To Commands」(コマンドへの応答)を参照してください。

fast-importが指定の機能をサポートすることを要求するか、サポートしない場合は中止(abort)します。

コマンドの <feature> 部分は、以下のいずれかになります:

指定されたオプションを処理して、git fast-importがフロントエンドのニーズに合った方法で動作するようにします。 フロントエンドで指定されたオプションは、ユーザーがgit fast-import自体に指定したオプションによって上書きされることに注意してください。

コマンドの <option> 部分には、OPTIONSセクションにリストされているオプションのいずれかを含めることができます。これらのオプションは、先頭の -- がなくても、インポートのセマンティクスを変更せず、同じように扱われます。

optionコマンドは、非オプションコマンドがエラーになった後にオプションコマンドを与えるために、入力の最初のコマンドである必要があります(featureコマンドはカウントされません)。

以下のコマンドラインオプションはインポートセマンティクスを変更するため、オプションとして渡されない場合があります:

done 機能が使用されていない場合は、EOFが読み取られたかのように扱われます。 これを使用して、fast-importに早期に終了するように指示できます。

--done コマンドラインオプションまたは feature done コマンドが使用されている場合、 done コマンドは必須であり、ストリームの終わりを示します。

リポジトリ変換を行うときは、コミットごとに一意のマーク(mark :<n>)を使用し、コマンドラインで --export-marks オプションを指定します。 fast-importは、すべてのマークとそれに対応するGitオブジェクトSHA-1をリストするファイルをダンプします。 フロントエンドがマークをソースリポジトリに結び付けることができる場合、各Gitコミットを対応するソースリビジョンと比較することで、インポートの正確性と完全性を簡単に確認できます。

PerforceやSubversionなどのシステムから来る場合、これは非常に単純なはずです。fast-importマークは、Perforceのチェンジセット番号またはSubversionのリビジョン番号でもある可能性があるためです。

インポート中に一度に1つのブランチに固執するようにフロントエンドをわざわざ最適化しようとしないでください。 これを行うと、fast-importの場合は少し速くなる可能性がありますが、フロントエンドコードの複雑さが大幅に増す傾向があります。

高速インポートに組み込まれているブランチLRUは非常に適切に動作する傾向があり、非アクティブなブランチをアクティブ化するコストは非常に低いため、ブランチ間でのバウンスはインポートのパフォーマンスに実質的に影響しません。

名前を変更したファイルまたはディレクトリをインポートするときは、対応するコミット中に古い名前を削除し、新しい名前を変更するだけです。 Gitは、コミット中に明示的にではなく、事後に名前変更の検出を実行します。

他のいくつかのSCMシステムでは、ユーザーは同じ コミット/チェンジセット からではない複数のファイルからタグを作成できます。 または、リポジトリで使用可能なファイルのサブセットであるタグを作成します。

これらのタグをそのままGitにインポートするには、タグのコンテンツと一致するようにファイルを「修正」するコミットを少なくとも1つ実行する必要があります。 fast-importの reset コマンドを使用して、通常のブランチスペースの外側にあるダミーブランチをタグのベースコミットにリセットし、1つ以上のファイル修正コミットをコミットして、最後にダミーブランチにタグを付けます。

たとえば、すべての通常のブランチは refs/heads/ の下に保存されるため、タグ修正ブランチには TAG_FIXUP という名前を付けます。 このように、インポーターによって使用される修正ブランチが、ソースからインポートされた実際のブランチと名前空間の競合を持つことは不可能です(名前 TAG_FIXUP は refs/heads/TAG_FIXUP ではありません)。

フィックスアップ(fixup)をコミットするときは、 merge を使用してファイルリビジョンを提供しているコミットをフィックスアップブランチに接続することを検討してください。 そうすることで、 git blame などのツールが実際のコミット履歴を追跡し、ソースファイルに適切に注釈を付けることができます。

fast-importが終了した後、フロントエンドはダミーブランチを削除するために rm .git/TAG_FIXUP を実行する必要があります。

fast-importが完了するとすぐに、Gitリポジトリは完全に有効になり、使用できるようになります。 通常、これは非常に大規模なプロジェクト(100,000以上のコミット)の場合でも、非常に短い時間しかかかりません。

ただし、データの局所性とアクセスパフォーマンスを向上させるには、リポジトリを再パックする必要があります。 また、非常に大規模なプロジェクトでは数時間かかる場合があります(特に、 -f および 大きな --window パラメーターが使用されている場合)。 再パックはリーダーやライターと一緒に実行しても安全なので、バックグラウンドで再パックを実行し、再パックが終了したらリーダーやライターを終了させます。 あなたが新しいGitプロジェクトに挑戦するのを待たされる事はありません！

あなたが再パックを待つことを選択した場合は、再パックが完了するまでベンチマークやパフォーマンステストを実行しないでください。 その場合、 fast-importは、実際の使用状況では決して見られないような、最適でないパックファイルを出力します。

非常に古くにインポートされたデータ(たとえば、昨年より古い)を再パックする場合は、 git repack を実行するときに、 --window=50 (またはそれ以上)を指定して余分なCPU時間を費やすことを検討してください。 これには時間がかかりますが、作成されるパックファイルも小さくなります。 あなたが労力を費やす必要があるのは1回だけで、あなたのプロジェクトを使用するすべての人が小さくなったリポジトリの恩恵を受けることができます。

時々、フロントエンドに progress メッセージを送信してfast-importします。 メッセージの内容は完全に自由形式であるため、現在のコミット日が翌月に移動するたびに、現在の月と年を出力することをお勧めします。あなたのユーザーは、処理されたデータストリームの量をよりよく知ることができます。

fast-importは、この実行で書き込まれるすべてのオブジェクトのメモリ内構造を維持します。 32ビットシステムでは、構造は32バイトですが、64ビットシステムでは、構造は40バイトです(ポインタサイズが大きいため)。 テーブル内のオブジェクトは、fast-importが終了するまで割り当てが解除されません。 32ビットシステムに200万個のオブジェクトをインポートするには、約64MiBのメモリが必要です。

オブジェクトテーブルは、実際にはオブジェクト名(一意のSHA-1)をキーとするハッシュテーブルです。 このストレージ構成により、fast-importで既存または既に書き込まれたオブジェクトを再利用し、出力パックファイルへの重複の書き込みを回避できます。 インポートでは、ブロブの重複が驚くほど一般的です。これは通常、ソースでのブランチのマージが原因です。

マークは、マークごとに1つのポインター(ポインターのサイズに応じて4バイトまたは8バイト)を使用して、まばらな配列に格納されます。 配列はまばらですが、フロントエンドでは 1〜n のマークを使用することを強くお勧めします。ここで、n はこのインポートに必要なマークの総数です。

ブランチはアクティブと非アクティブにクラス分けされます。 2つのクラスのメモリ使用量は大幅に異なります。

非アクティブなブランチは、ブランチごとに96バイトまたは120バイト(それぞれ32ビットまたは64ビットシステム)とブランチ名の長さ(通常は200バイト未満)を使用する構造に格納されます。 fast-importは、2MiB未満のメモリで10,000もの非アクティブなブランチを簡単に処理します。

アクティブなブランチには非アクティブなブランチと同じオーバーヘッドがありますが、そのブランチで最近変更されたすべてのツリーのコピーも含まれています。 ブランチがアクティブになってからサブツリー include が変更されていない場合、その内容はメモリに読み込まれませんが、ブランチがアクティブになってからコミットによってサブツリー src が変更されている場合、その内容はメモリに読み込まれます。

アクティブなブランチは、そのブランチに含まれるファイルに関するメタデータを格納するため、メモリ内のストレージサイズがかなり大きくなる可能性があります(以下参照)。

fast-importは、単純な「最も最近使用されていない」アルゴリズム(least-recently-used algorithm)に基づいて、アクティブなブランチを自動的に非アクティブなステータスに移動します。 LRUチェーンは、commit コマンドごとに更新されます。 アクティブなブランチの最大数は、コマンドラインで --active-branches= を使用して増減できます。

ツリー(別名ディレクトリ)は、エントリに必要なメモリに加えて、わずか12バイトのメモリを使用します(以下「per active file」参照)。 ツリーのオーバーヘッドは個々のファイルエントリで償却されるため、ツリーのコストは実質的に0です。

アクティブツリー内のファイル(およびサブツリーへのポインター)には、エントリごとに52バイトまたは64バイト(32/64 ビットプラットフォーム)が必要です。 スペースを節約するために、ファイル名とツリー名は共通の文字列テーブルにプールされ、ファイル名 Makefile が(文字列ヘッダーのオーバーヘッドを含めた後)、プロジェクト内で何度発生しても、わずか16バイトしか使用しないようにします。

アクティブブランチLRUは、ファイル名文字列プールおよびサブツリーの遅延読み込みと組み合わせると、fast-importにより、非常に限られたメモリフットプリント(アクティブブランチあたり2.7 MiB未満)で2,000以上のブランチと45,114以上のファイルを持つプロジェクトを効率的にインポートできます。