日本語 ▾ トピック ▾ 最新バージョン ▾ git-pack-objects は 2.49.0 で最終更新されました

名前

git-pack-objects - オブジェクトのパックされたアーカイブを作成する

概要

git pack-objects [-q | --progress | --all-progress] [--all-progress-implied]
	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
	[--local] [--incremental] [--window=<n>] [--depth=<n>]
	[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
	[--cruft] [--cruft-expiration=<time>]
	[--stdout [--filter=<filter-spec>] | <base-name>]
	[--shallow] [--keep-true-parents] [--[no-]sparse]
	[--name-hash-version=<n>] < <object-list>

説明

標準入力からオブジェクトのリストを読み込み、指定されたベース名を持つ1つ以上のパックアーカイブをディスクに書き込むか、パックアーカイブを標準出力に書き込みます。

パックアーカイブは、2つのリポジトリ間でオブジェクトのセットを転送する効率的な方法であり、アクセス効率の良いアーカイブ形式でもあります。パックアーカイブでは、オブジェクトは圧縮された全体として保存されるか、他のオブジェクトからの差分として保存されます。後者はしばしばデルタと呼ばれます。

パックアーカイブ形式 (.pack) は、追加情報なしで解凍できるように自己完結型に設計されています。そのため、デルタが依存する各オブジェクトはパック内に存在する必要があります。

パック内のオブジェクトへの高速ランダムアクセスを可能にするため、パックインデックスファイル (.idx) が生成されます。インデックスファイル (.idx) とパックアーカイブ (.pack) の両方を $GIT_OBJECT_DIRECTORY (または $GIT_ALTERNATE_OBJECT_DIRECTORIES のいずれかのディレクトリ) の pack/ サブディレクトリに配置すると、Git はパックアーカイブから読み取ることができます。

git unpack-objects コマンドは、パックアーカイブを読み取り、パックに含まれるオブジェクトを「1ファイル1オブジェクト」形式に展開できます。これは通常、スマートプルコマンドが、ピアによる効率的なネットワーク転送のためにパックをオンザフライで作成するときに行われます。

オプション

base-name

<base-name> を使用して作成されるファイルの名前を決定し、ファイルのペア (.pack と .idx) に書き込みます。このオプションを使用する場合、ペア内の2つのファイルは <base-name>-<SHA-1>.{pack,idx} ファイルに書き込まれます。<SHA-1> はパックの内容に基づいたハッシュであり、コマンドの標準出力に書き込まれます。

--stdout

パックの内容 (.pack ファイルに書き込まれるはずだったもの) を標準出力に書き込みます。

--revs

個々のオブジェクト名ではなく、標準入力からリビジョン引数を読み込みます。リビジョン引数は、--objects フラグを持つ git rev-list がその commit 引数を使用して出力するオブジェクトのリストを作成するのと同じ方法で処理されます。結果のリスト上のオブジェクトはパックされます。リビジョンの他に、--not または --shallow <SHA-1> 行も受け入れられます。

--unpacked

これは --revs を意味します。標準入力から読み取られたリビジョン引数のリストを処理するとき、パックされるオブジェクトを、まだパックされていないものに限定します。

--all

これは --revs を意味します。標準入力から読み取られたリビジョン引数のリストに加えて、refs/ 以下のすべての参照が含まれるように指定されたかのように扱います。

--include-tag

参照されるオブジェクトが結果のパックファイルに含まれている場合、要求されていない注釈付きタグを含めます。これは、新しいタグをネイティブGitクライアントに送信する場合に役立ちます。

--stdin-packs

オブジェクト名やリビジョン引数ではなく、標準入力からパックファイルのベース名 (例: pack-1234abcd.pack) を読み込みます。結果のパックには、含まれるパック (先頭に ^ がないもの) にリストされているすべてのオブジェクトが含まれ、除外されるパック (先頭に ^ があるもの) にリストされているオブジェクトは除外されます。

--revs、または --revs を暗示するオプション (例: --all) とは互換性がありません。ただし、--unpacked は互換性があります。

--cruft

到達不能なオブジェクトを、.mtimes ファイルの存在によって示される別の「cruft」パックにパックします。通常、git repack --cruft で使用されます。呼び出し元はパック名のリストを提供し、どのパックがリポジトリに残るか、およびどのパックが削除されるか (- プレフィックスで示されます) を示します。cruft パックの内容は、残存するパックに含まれておらず、猶予期間 (以下の --cruft-expiration を参照) を超えていない、または猶予期間を超えているが、超えていない別のオブジェクトから到達可能なすべてのオブジェクトです。

入力が到達可能なすべてのオブジェクトを含むパックをリストし(他のすべてのパックを削除保留中としてリストする)、対応するcruftパックには、到達不能なすべてのオブジェクト(--cruft-expirationよりも新しいmtimeを持つもの)と、mtimeが--cruft-expirationよりも古いが、mtimeが--cruft-expirationよりも新しい到達不能なオブジェクトから到達可能な到達不能なオブジェクトが含まれます)。

--unpack-unreachable--keep-unreachable--pack-loose-unreachable--stdin-packs、および --revs を暗示するその他のオプションとは互換性がありません。

--cruft-expiration=<approxidate>

指定された場合、mtimeが<approxidate>よりも古いオブジェクトは、cruftパックから除外されます。指定されていない場合(および--cruftが指定されている場合)、オブジェクトは除外されません。

--window=<n>
--depth=<n>

これら2つのオプションは、パックに含まれるオブジェクトがデルタ圧縮を使用してどのように保存されるかに影響します。オブジェクトは、まず内部的にタイプ、サイズ、オプションで名前によってソートされ、--window 内の他のオブジェクトと比較されて、デルタ圧縮を使用するとスペースが節約されるかどうかを確認します。--depth は最大デルタ深度を制限します。深度が深すぎると、アンパッカー側のパフォーマンスに影響します。なぜなら、必要なオブジェクトに到達するためにデルタデータを何度も適用する必要があるからです。

--window のデフォルト値は 10、--depth のデフォルト値は 50 です。最大深度は 4095 です。

--window-memory=<n>

このオプションは、--window の上にさらなる制限を提供します。ウィンドウサイズは、メモリ内で <n> バイトを超えないように動的に縮小されます。これは、大小のオブジェクトが混在するリポジトリで、大きなウィンドウを使用してもメモリ不足にならないようにしながら、小さなオブジェクトに対して大きなウィンドウの利点を活用できるようにする場合に役立ちます。サイズは「k」、「m」、または「g」の接尾辞を付けることができます。--window-memory=0 はメモリ使用量を無制限にします。デフォルトは pack.windowMemory 設定変数から取得されます。

--max-pack-size=<n>

まれなシナリオでは、ファイルシステム上で特定のサイズを超えるファイルを作成できない場合があります。このオプションは、コマンドに対して、出力パックファイルを、指定されたサイズを超えない複数の独立したパックファイルに分割するように指示するために使用できます。サイズには「k」、「m」、または「g」の接尾辞を付けることができます。許可される最小サイズは 1 MiB に制限されています。設定変数 pack.packSizeLimit が設定されていない限り、デフォルトは無制限です。このオプションを使用すると、リポジトリが大きくなり、処理が遅くなる可能性があることに注意してください。pack.packSizeLimit の説明を参照してください。

--honor-pack-keep

このフラグを指定すると、.keep ファイルを持つローカルパックにすでに存在するオブジェクトは、そうでなければパックされるはずであっても無視されます。

--keep-pack=<pack-name>

このフラグを指定すると、指定されたパックにすでに存在するオブジェクトは、そうでなければパックされるはずであっても無視されます。<pack-name> は、先頭のディレクトリを含まないパックファイル名です (例: pack-123.pack)。複数のパックを保持するために、このオプションを複数回指定できます。

--incremental

このフラグを指定すると、パック内にすでに存在するオブジェクトは、そうでなければパックされるはずであっても無視されます。

--local

このフラグを指定すると、代替オブジェクトストアから借りたオブジェクトは、そうでなければパックされるはずであっても無視されます。

--non-empty

少なくとも1つのオブジェクトが含まれる場合にのみ、パックアーカイブを作成します。

--progress

デフォルトでは、標準エラー出力ストリームがターミナルに接続されている場合、-q が指定されない限り、進行状況が標準エラー出力ストリームに報告されます。このフラグは、標準エラー出力ストリームがターミナルに接続されていない場合でも、進行状況を強制的に表示します。

--all-progress

--stdout が指定されている場合、オブジェクトのカウントと圧縮段階では進捗レポートが表示されますが、書き出し段階では抑制されます。これは、場合によっては出力ストリームが別のコマンドに直接リンクされており、そのコマンドが受信するパックデータを処理する際に自身の進捗ステータスを表示したい場合があるためです。このフラグは --progress と同様ですが、--stdout が使用されている場合でも書き出し段階の進捗レポートを強制します。

--all-progress-implied

これは、進捗表示がアクティブ化されるたびに --all-progress を暗黙的に指定するために使用されます。--all-progress とは異なり、このフラグ自体は進捗表示を強制しません。

-q

このフラグを指定すると、コマンドは標準エラー出力に進捗状況を報告しません。

--no-reuse-delta

既存のパックがあるリポジトリにパックアーカイブを作成する場合、コマンドは既存のデルタを再利用します。これは時として、わずかに最適でないパックになることがあります。このフラグは、既存のデルタを再利用せずにゼロから計算するようにコマンドに指示します。

--no-reuse-object

このフラグは、デルタ化されていないオブジェクトを含む既存のオブジェクトデータを一切再利用せず、すべてを再圧縮するようにコマンドに指示します。これは --no-reuse-delta を意味します。これは、パックされたデータに異なる圧縮レベルを一括で強制したいという珍しい場合にのみ役立ちます。

--compression=<n>

生成されるパック内の新しく圧縮されたデータの圧縮レベルを指定します。指定されていない場合、パック圧縮レベルは、まず pack.compression、次に core.compression によって決定され、どちらも設定されていない場合は zlib のデフォルトである -1 になります。ソースに関係なく、すべてのデータに均一な圧縮レベルを強制したい場合は、--no-reuse-object を追加します。

--[no-]sparse

"--revs" オプションと組み合わせた場合、パックに含めるオブジェクトを決定するための「スパース」アルゴリズムを切り替えます。このアルゴリズムは、新しいオブジェクトを導入するパスに表示されるツリーのみを辿ります。これにより、小さな変更を送信するためのパックを計算する際に、パフォーマンスが大幅に向上する可能性があります。ただし、含まれるコミットに特定の種類の直接的な名前変更が含まれている場合、余分なオブジェクトがパックファイルに追加される可能性があります。このオプションが含まれていない場合、pack.useSparse の値がデフォルトとなり、これは特に指定がない限り true です。

--thin

ネットワーク転送を削減するために、送信者と受信者の間で共通のオブジェクトを省略して「シン」パックを作成します。このオプションは、--stdout と組み合わせてのみ意味があります。

注記: シンパックは、必要なオブジェクトを省略することでパックアーカイブ形式に違反するため、自己完結型にしないとGitでは使用できません。git index-pack --fix-thin (git-index-pack[1] を参照) を使用して自己完結型の特性を復元してください。

--shallow

シャローリポジトリを持つクライアントに提供されるパックを最適化します。このオプションは、--thin と組み合わせることで、速度を犠牲にしてより小さなパックを作成できます。

--delta-base-offset

パックアーカイブは、デルタのベースオブジェクトを20バイトのオブジェクト名またはストリーム内のオフセットとして表現できますが、古いバージョンのGitは後者を理解しません。デフォルトでは、git pack-objects は互換性を高めるために前者の形式のみを使用します。このオプションを使用すると、コマンドは後者の形式を使用してコンパクトにすることができます。平均デルタチェーン長によっては、このオプションは通常、結果のパックファイルを3-5パーセント縮小します。

注: git gc (git-gc[1] を参照)、git repack (git-repack[1] を参照) などのポーセリンコマンドは、現代のGitでは、オブジェクトをリポジトリ内のパックファイルに入れる際にデフォルトでこのオプションを渡します。また、git bundle (git-bundle[1] を参照) もバンドルを作成する際に同様に渡します。

--threads=<n>

最適なデルタ一致を検索する際に生成するスレッド数を指定します。これには pack-objects が pthreads でコンパイルされている必要があり、そうでない場合このオプションは警告とともに無視されます。これはマルチプロセッサマシンでのパック時間を短縮するためのものです。ただし、デルタ検索ウィンドウに必要なメモリ量はスレッド数によって乗算されます。0 を指定すると、Git は CPU の数を自動検出し、それに応じてスレッド数を設定します。

--index-version=<version>[,<offset>]

これはテストスイートのみでの使用を意図しています。生成されるパックインデックスのバージョンを強制し、指定されたオフセットより上にあるオブジェクトに64ビットインデックスエントリを強制することを可能にします。

--keep-true-parents

このオプションを使用すると、グラフトによって隠されている親もパックされます。

--filter=<filter-spec>

結果のパックファイルから特定のオブジェクト(通常はブロブ)を省略します。<filter-spec> の有効な形式については、git-rev-list[1] を参照してください。

--no-filter

以前の --filter= 引数を無効にします。

--missing=<missing-action>

将来の「部分クローン」開発に役立つデバッグオプションです。このオプションは、不足しているオブジェクトの処理方法を指定します。

形式 --missing=error は、不足しているオブジェクトが見つかった場合、pack-objects がエラーで停止するように要求します。リポジトリが部分クローンである場合、不足しているオブジェクトとして宣言する前に、不足しているオブジェクトをフェッチしようと試みます。これがデフォルトのアクションです。

形式 --missing=allow-any は、不足しているオブジェクトが見つかった場合でも、オブジェクトの走査を続行させます。不足しているオブジェクトのフェッチは行われません。不足しているオブジェクトは結果から黙って省略されます。

形式 --missing=allow-promisorallow-any と似ていますが、予期されるプロミッサー不足オブジェクトの場合にのみ、オブジェクトの走査を続行させます。不足しているオブジェクトのフェッチは行われません。予期しない不足オブジェクトはエラーを発生させます。

--exclude-promisor-objects

プロミサーリモートに存在することがわかっているオブジェクトを省略します。(このオプションは、ローカルで作成されたオブジェクトのみを操作する目的を持ち、再パックする際に、ローカルで作成されたオブジェクト [.promisorなし] とプロミサーリモートからのオブジェクト [.promisorあり] の区別を維持するためです。) これは部分クローンで使用されます。

--keep-unreachable

--unpacked= オプションで指定されたパック内の参照から到達不能なオブジェクトは、*.keep ファイルでマークされていない到達可能なオブジェクトに加えて、結果のパックに追加されます。これは --revs を意味します。

--pack-loose-unreachable

到達不能なルーズオブジェクトをパックします(そしてそのルーズな対応物を削除します)。これは --revs を意味します。

--unpack-unreachable

到達不能なオブジェクトをルーズ形式で保持します。これは --revs を意味します。

--delta-islands

「アイランド」に基づいてデルタ一致を制限します。以下の DELTA ISLANDS を参照してください。

--name-hash-version=<n>

デルタ圧縮を実行する際、Gitはオブジェクトへのパスを使用するヒューリスティックに基づいて、類似している可能性のあるオブジェクトをグループ化します。正確なパス一致でオブジェクトをグループ化することは、多くのバージョンを持つパスには適していますが、異なるフルパス間でデルタペアを見つけることには利点があります。Gitはタイプ別に、次にパスの「名前ハッシュ」別に、そしてサイズ別にオブジェクトを収集し、うまく圧縮できるオブジェクトをグループ化しようとします。

デフォルトの名前ハッシュバージョンは 1 であり、パスの最終バイトがハッシュ関数に最大の強度を提供すると考えてハッシュの局所性を優先します。このバージョンは短いパスを区別し、ディレクトリ間の名前変更を見つけるのに優れています。ただし、ハッシュ関数は主にパスの最終16バイトに依存します。リポジトリに同じ最終16バイトを持ち、親ディレクトリのみが異なる多くのパスがある場合、この名前ハッシュは衝突を多く引き起こし、結果が劣る可能性があります。現時点では、--write-bitmap-index で到達可能性ビットマップファイルを書き込む場合、このバージョンが必要です。

名前ハッシュバージョン 2 は、バージョン 1 と同様の局所性機能を持っていますが、各パスコンポーネントを個別に考慮し、ハッシュをシフトで重ね合わせます。これにより、パスの最終バイトは依然として優先されますが、親ディレクトリ名を使用してハッシュの下位ビットも「ソルト」されます。このメソッドは、バージョン 1 の局所性の一部を維持しつつ、多くの異なるディレクトリに同じ名前のファイルが出現することによるほとんどの衝突を解消します。現時点では、--write-bitmap-index で到達可能性ビットマップファイルを書き込む場合、このバージョンは許可されておらず、自動的にバージョン 1 に変更されます。

デルタアイランド

可能であれば、pack-objects は既存のオンディスクデルタを再利用して、新しいデルタをその場で検索する必要がないようにします。これはフェッチを処理するための重要な最適化であり、サーバーがほとんどのオブジェクトを膨張させることなく、ディスクからバイトを直接送信できることを意味します。この最適化は、受信者が持っていない (かつまだ送信していない) ベースに対してオブジェクトがデルタとして格納されている場合には機能しません。その場合、サーバーはデルタを「破壊」し、新しいデルタを見つける必要がありますが、これには高いCPUコストがかかります。したがって、オンディスクデルタ関係にあるオブジェクトのセットがクライアントがフェッチするものと一致することがパフォーマンスにとって重要です。

通常のリポジトリでは、これは自動的に機能する傾向があります。オブジェクトはほとんどブランチやタグから到達可能であり、それがクライアントがフェッチするものです。サーバーで見つかるデルタは、クライアントが持っているか、これから持つオブジェクト間のものである可能性が高いです。

しかし、一部のリポジトリ設定では、関連するが分離された複数の参照チップのグループがあり、クライアントがそれらのグループを独立してフェッチする傾向がある場合があります。たとえば、単一の共有オブジェクトストアでリポジトリのいくつかの「フォーク」をホストし、GIT_NAMESPACE または代替メカニズムを使用してクライアントがそれらを個別のリポジトリとして表示できるようにしていると想像してください。素朴な再パックでは、オブジェクトの最適なデルタが別のフォークでのみ見つかるベースに対してであると判明する場合があります。しかし、クライアントがフェッチする場合、ベースオブジェクトを持たないため、その場で新しいデルタを見つける必要があります。

同様の状況は、refs/heads/ および refs/tags/ 以外に、関連オブジェクトを指す多くの参照 (例: 一部のホスティングプロバイダーが使用する refs/pull または refs/changes) がある場合にも存在する可能性があります。デフォルトでは、クライアントはヘッドとタグのみをフェッチし、これらの他のグループにのみ存在するオブジェクトに対するデルタはそのまま送信できません。

デルタアイランドは、参照を異なる「アイランド」にグループ化することでこの問題を解決します。Pack-objectsは、どのアイランドからどのオブジェクトが到達可能かを計算し、オブジェクトAのすべてのアイランドに存在しないベースに対してデルタを作成することを拒否します。これにより、パックはわずかに大きくなりますが(一部のデルタ機会を逃すため)、あるアイランドのフェッチがアイランド境界を越えることによってその場でデルタを再計算する必要がないことを保証します。

デルタアイランドを使用して再パックする場合、デルタウィンドウは設定によって禁止されている候補で詰まる傾向があります。大きな --window で再パックすると役立ちます(内容に対して計算を行う前に、アイランドに基づいて一部のオブジェクトペアを拒否できるため、それほど時間はかかりません)。

アイランドは pack.island オプションを介して設定され、複数回指定できます。各値は、参照名と一致する左アンカー正規表現です。例えば、

[pack]
island = refs/heads/
island = refs/tags/

ヘッドとタグを1つのアイランド(名前は空の文字列。命名の詳細については以下を参照)に配置します。これらの正規表現に一致しない参照(例: refs/pull/123)はどのアイランドにも属しません。したがって、refs/pull/ からのみ到達可能なオブジェクト(ただしヘッドまたはタグからは到達不能)は、refs/heads/ のベースとして使用される候補にはなりません。

参照は、その「名前」に基づいてアイランドにグループ化され、同じ名前を生成する2つの正規表現は同じアイランドにあると見なされます。名前は、正規表現からキャプチャグループを連結し、間に - ダッシュを挟むことで計算されます(キャプチャグループがない場合、上記例のように名前は空の文字列になります)。これにより、任意の数のアイランドを作成できます。ただし、サポートされるキャプチャグループは最大14個です。

たとえば、各フォークの参照を refs/virtual/ID に保存し、ID が数値識別子であるとします。その場合、次のように設定できます。

[pack]
island = refs/virtual/([0-9]+)/heads/
island = refs/virtual/([0-9]+)/tags/
island = refs/virtual/([0-9]+)/(pull)/

これにより、各フォークのヘッドとタグが独自のアイランド(「1234」のような名前)に配置され、各フォークのプル参照は独自の「1234-pull」に移動します。

各正規表現が属する単一のアイランドを選択することに注意してください。「最後のものが優先される」順序(これにより、リポジトリ固有の設定がユーザー全体の設定よりも優先されるなど)が使用されます。

設定

様々な設定変数がパックに影響を与えます。git-config[1] (「pack」と「delta」で検索) を参照してください。

特に、core.bigFileThreshold 設定変数よりも大きいオブジェクトや、delta 属性が false に設定されているファイルにはデルタ圧縮は使用されません。

GIT

git[1]スイートの一部

scroll-to-top