フロントエンドのデバッグを支援するため、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 の有効なリファレンス名である必要があります。LF は Git のリファレンス名では無効なため、ここでは引用符付けやエスケープ構文はサポートされていません。

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

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

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

コマンドの後の 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 以上の値のみを使用できます。

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

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

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

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

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

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

<name> の値は Git の有効なリファレンス名である必要があり、したがってフォワードスラッシュを含むことができます。LF は Git のリファレンス名では無効なため、ここでは引用符付けやエスケープ構文はサポートされていません。

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

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

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

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

指定された名前のブランチを作成 (または再作成) し、オプションで特定の改訂から開始します。reset コマンドにより、フロントエンドは既存のブランチに対して新しい from コマンドを発行したり、新しいコミットを作成せずに既存のコミットから新しいブランチを作成したりできます。

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

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

reset コマンドは軽量 (注釈なし) タグを作成するためにも使用できます。例えば、

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

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

ここでのマークコマンドはオプションです。一部のフロントエンドは、ブロブの Git SHA-1 を独自に生成し、それを直接 commit に渡すことを選択しているためです。しかし、マークは保存コストが低く、使いやすいため、通常はそれだけの価値はありません。

生のデータ (ブロブ/ファイルの内容、コミットメッセージ、注釈付きタグメッセージとして使用) を fast-import に供給します。データは、正確なバイト数で指定するか、終端行で区切って指定できます。本番品質の変換を意図した実際のフロントエンドは、より堅牢でパフォーマンスが優れているため、常に正確なバイト数形式を使用すべきです。区切り形式は主に fast-import のテストを目的としています。

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

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

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

fast-import に現在のパックファイルを閉じ、新しいパックファイルを開始し、現在のすべてのブランチリファレンス、タグ、マークを保存するよう強制します。

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

checkpoint は、かなりの量の CPU 時間とディスク IO (全体的なパック SHA-1 チェックサムの計算、対応するインデックスファイルの生成、およびリファレンスの更新) を必要とするため、単一の 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 が更新したリファレンスに安全にアクセスできるようになったことを読み取り側に通知します。

fast-import が、マークに対応する SHA-1 を標準出力または以前に --cat-blob-fd 引数で設定されたファイルディスクリプタに出力するようにします。このコマンドは、それ以外の場合、現在のインポートに影響を与えません。その目的は、後のコミットがコミットメッセージで参照したい SHA-1 を取得することです。

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

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

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

出力は git cat-file --batch と同じフォーマットを使用します。

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

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

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

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

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

出力は git ls-tree <tree> -- <path> と同じフォーマットを使用します。

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

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

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

fast-import が指定された機能をサポートしていることを要求します。サポートしていない場合は中断します。

コマンドの <feature> 部分は以下のいずれかです。

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

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

オプションコマンドは入力の一番最初 (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 がわずかに高速になるかもしれませんが、フロントエンドコードの複雑さを大幅に増加させる傾向があります。

fast-import に組み込まれているブランチ LRU (Least Recently Used) は非常にうまく機能する傾向があり、非アクティブなブランチをアクティブにするコストは非常に低いため、ブランチ間を行き来してもインポートパフォーマンスにはほとんど影響しません。

名前変更されたファイルまたはディレクトリをインポートする場合、対応するコミットで単に古い名前を削除し、新しい名前を変更します。Git は、コミット中に明示的にではなく、後から名前変更を検出します。

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

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

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

修正をコミットする際、ファイルのリビジョンを提供するコミットを修正ブランチに接続するために merge を使用することを検討してください。これにより、git blame のようなツールが実際のコミット履歴を追跡し、ソースファイルを適切に注釈付けできるようになります。

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

fast-import が完了すると、Git リポジトリは完全に有効になり、すぐに使用できます。通常、これは非常に短時間で完了し、非常に大規模なプロジェクト (10万以上のコミット) であっても同様です。

ただし、データ局所性とアクセスパフォーマンスを向上させるためには、リポジトリのリパックが必要です。これは非常に大規模なプロジェクトでは数時間かかることもあります (特に -f と大きな --window パラメータが使用されている場合)。リパックは読み取りと書き込みと並行して安全に実行できるため、バックグラウンドでリパックを実行し、完了したら完了させます。新しい Git プロジェクトを探索するのを待つ理由はありません！

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

非常に古いインポートデータ (例: 昨年以前のもの) をリパックしている場合、git repack を実行する際に、追加の CPU 時間を費やして --window=50 (またはそれ以上) を指定することを検討してください。これには時間がかかりますが、より小さなパックファイルが生成されます。この労力は一度だけで済み、プロジェクトを使用するすべての人がより小さなリポジトリの恩恵を受けることができます。

時々、フロントエンドに fast-import へ progress メッセージを出力させてください。メッセージの内容は完全に自由形式なので、現在のコミット日が次の月に移るたびに、現在の月と年を出力することをお勧めします。データストリームがどれだけ処理されたかを知ることで、ユーザーは安心感を覚えるでしょう。

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

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

マークはスパース配列に格納され、マークごとに1ポインタ（ポインタサイズに応じて4バイトまたは8バイト）を使用します。配列はスパースですが、フロントエンドは依然として1からnまでのマークを使用することを強く推奨されています。ここでnはこのインポートに必要なマークの総数です。

ブランチはアクティブと非アクティブに分類されます。両クラスのメモリ使用量は大きく異なります。

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

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

アクティブなブランチは、そのブランチに含まれるファイルに関するメタデータを格納するため、インメモリのストレージサイズがかなりの大きさになることがあります（下記参照）。

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

ツリー（ディレクトリとも呼ばれる）は、そのエントリに必要なメモリ（下記の「アクティブなファイルごと」を参照）に加えて、わずか12バイトのメモリを使用します。ツリーのオーバーヘッドは個々のファイルエントリに償却されるため、そのコストは実質的に0です。

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

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