sparse-checkout は、 ユーザーのファイル群のサブセットを操作できるようにするために存在します。

sparse-checkouts は、「追跡中のファイル」を 2 つのカテゴリ — スパース・サブセットとその他すべて — に再分割するものと考えることができます。 その実装としては、 インデックス内の「残りすべて」を SKIP_WORKTREE ビットでマークし、 作業ツリーから除外します。 SKIP_WORKTREE ビットをマークしたファイルは引き続き追跡中ですが、 作業ツリーには存在しないだけです。

以前は、スパース・チェックアウトは「SKIP_WORKTREE とは、 そのファイルが作業ツリーから欠落しているが、 ファイルの内容が HEAD と一致するかのように装うことを意味する」と定義していました。 それはインチキ(実際には、 作業ツリーで欠落しているファイルが HEAD ではなくインデックスと一致することを意味していました)であるだけでなく、いくつかのコマンドにしかまともな動作を提供しない低レベルのものだった。 その指導原理がユーザーの期待に反するような結果をもたらすことは驚くほど多く、 よくない概念モデルであった。 しかし、それは長年にわたって存在したので、 今でもコードベースの片隅に残っているかもしれません。

とにかく、 「ファイル群のサブセットを操作する」という考え方は非常に単純ですが、 一部の Git サブコマンドの動作に影響を与える、 複数の異なる高レベルのユースケースが存在します。 さらに、これらのユースケースの 1 つだけを考慮したとしても、 スパース・チェックアウトはさまざまなサブコマンドを 6 種類以上の異なる方法で変更できます。 まずは、以下のような高レベルのユースケースを検討してみましょう。

これらのそれぞれをもう少し詳しく説明する価値があるかもしれません:

ユーザーは、 リポジトリに他のものが存在することを知っているかもしれませんが、 気にしません。 ユーザーはリポジトリの他の部分には興味がなく、 関心のある領域内の変更についてのみ知りたいと考えています。 履歴の他のファイル達(たとえば diff/log/grep/ など)を表示することは、有用性を損なう事であり、 履歴の他の部分の変更達が、 ユーザーが興味を持っている変更を矮小化する可能性があるため、 大きな迷惑になる可能性がある。

これらのユーザーの中には、部分(partial)クローンを、(スパース仕様内の BLOB をダウンロードした方法で、)スパース・チェックアウトとともに使用し、 非接続開発を行うことを希望してこのユースケースにたどり着いた人もいます。 これらのユーザーは通常、 リポジトリの他の部分を気にしないだけでなく、 Git コマンドがそれらの部分を操作しようとするのを妨げるものであると考えています。 コマンドがスパース仕様の範囲外の履歴内のパスにアクセスしようとすると、 部分クローンはオンデマンドで追加の BLOB をダウンロードしようとしますが失敗し、 その後ユーザーのコマンドも失敗します。 (これは場合によっては避けられないかもしれません。たとえば、 git merge でスパース仕様の外側で調整するための重要な変更がある場合など、 ユーザーがネットワークに接続することを強制される頻度を制限する必要があります。)

また、 常にネットワークに接続していても構わない部分クローンを使用しているユーザーであっても、 他のさまざまなコマンド(マージまたはプル後に出力される diffstat など)の副作用として BLOB をダウンロードする必要があるため、 ローカル・リポジトリのサイズが不必要に増大するのではないかという懸念につながる可能性があります[10]。

このバリエーションは、 履歴クエリ操作のスパース仕様が、「スパース・パターン」から「既にダウンロードした BLOB に限定されたスパース・パターン」に変更された「振る舞いA」とみなすことができます。

Stolee はこのユースケースを以下のように説明しています[11]:

「また、 私はそれが大きな全体の一部であることを認識しているユーザーにも焦点を当てています。 彼らは大規模なリポジトリを操作していることを知っていますが、 自分たちが貢献するために必要な部分は何かに焦点を当てています。 複数の「担当」(roles)が、 まったく異なりほとんど結合していないコードベース部分を使用することが予想されます。 他の「設計」ユーザーの中には、 ツリー全体にわたって操作したり、 必要に応じてコードベースの異なるセクション間を行き来したりします。 この状況では、 スパースチェックアウト定義、 特に git log にあまりにも多くの機能の範囲を設定することには慎重であるべきで、それはコードベースの見方があなたの「観点」に依存すると非常に混乱する可能性があるためです。

また、 プロジェクト間の複雑な依存関係により、 最終的に「振る舞いB」が必要になる場合もあります。 スパース・チェックアウト(まばらなチェックアウト)を使用する最初の試みには、 通常、 直接関心のあるディレクトリと、 それらのディレクトリがリポジトリ内で依存しているものが含まれます。 しかし、 ここにそれを台無しにするものがあります(there’s a monkey wrench here)。 統合テストを行う場合、 序列が反転します。 統合テストを実行するには、 関心のあるものとそのツリー内の依存関係だけが必要なのではなく、 あなたが興味のあるものに依存するもの、 またはその依存関係のいずれかに依存するもの全ても必要で…そして、その展開されたグループのツリー内の依存関係がすべて必要です。 これにより、 あなたのスパース・チェックアウト(まばらなチェックアウト)をほぼ密なチェックアウトに簡単に変えることができます。

当然ながら、 これはチェックアウトがスパース(まばら)である利点を殺す傾向があります。 この難問に対する解決策がいくつかあります。 それは、 (たぶん、 あなたがどこかの CI キャッシュでプルしたリポジトリ内の依存関係のビルド・バージョンがあるでしょうから、 )リポジトリ内の依存関係を取得しないようにするか、 あるいは、 ユーザーが統合テストを直に実行せずにコード・レビューを送信するときに CI サーバー上で実行するよう指示する事です。 あるいはその両方を行います。 リポジトリ内の依存関係をもみ消すか、 依存しているものをもみ消すかに関係なく、 リポジトリの他のもみ消された部分の問い合わせを行って認識する必要があるのは確かで、 特に依存関係が複雑である場合や、 比較的頻繁に変更される場合には注意が必要です。 したがって、 そのような用途では、 スパース・チェックアウトを使用して、 直接に構築や変更するものを制限できますが、 これらのユーザーは、 スパース・チェックアウト・パスによって履歴内のバージョンの問い合わせを制限することを必ずしも望んでいる訳ではありません。

単純にパフォーマンス上の回避策として、 「振る舞いA」ではなく「振る舞いB」に興味を持つ人もいるかもしれません。 非円錐モードを使用している場合は、 非円錐モード固有の等比級数的パフォーマンス増大の問題に対処する必要があります。 このモードでは、 パスがスパース仕様にマッチするかどうかをチェックするすべての操作にコストがかかる可能性があります。 そのため、 これらのユーザーは、 作業コピーを操作するときにのみ高価なチェックにお金を払うつもりであり、 遅いコマンドを使用するよりも履歴クエリから「無関係な」結果を取得することを好む可能性があります。

このユースケースは、 実際に完全なチェックアウトまたは密なチェックアウトをユーザーに提示しようとするという点で、 スパース・チェックアウトの従来の定義に少々反しています。 ただし、 このユースケースでは、 同一の基礎技術基盤を新しいやりかたで利用することで、 ユーザーにパフォーマンス上の利点をもたらします。 基本的なアイデアとしては、 ある企業で社内用に Git 対応仮想ファイル・システムを持っていて、 そのすべてのファイル・システム・アクセスの傍受により、 部分クローンを介してオンデマンドでアクセスされたファイルを取り出したりしたり書き込んだりすることで、 すべてのファイルが作業ツリーに存在するかのように見せることができるというものです。 VFS はスパース・チェックアウトを使用して、 Git が多くのファイルに書き込んだり注意を払うのを防ぎ、 ユーザー・アクセスと作業ツリー内のファイルの変更に基づいてスパース・チェックアウト・パターン自体を手動で更新します。 このような VFS の詳細な説明については、コミット ecc7c8841d("repo_read_index: add config to expect files outside sparse patterns", 2022-02-25) と [17] のリンクを参照してください。

ここでの最大の違いは、 ユーザーはスパース・チェックアウト機構が使用中であることにまったく気づいていないことです。 スパース・パターンはユーザーによって指定されるのではなく、 VFS の完全な制御下にあります(そして、 パターンは VFS によって頻繁かつ動的に更新されます)。 ユーザーはチェックアウトが高密度(まばらでない)であると認識するため、 コマンドはすべてのファイルが存在するかのように動作する必要があります。

このドキュメントの残りの大部分は、 振る舞いA と 振る舞いB に焦点を当てます。 他の 2 つのケースと、それらに焦点を当てない理由についてもいくつか書いておきます:

このユースケースをサポートすることは難しく、 多大な労力がかかると予想されます。 現時点では実装の予定はありませんが、 将来的には代替手段となる可能性があります。 追加の代替手段の存在を知ることは、 コマンド・ライン・フラグの選択に影響を与える可能性があるため(たとえば、単なる2値フラグではなくトライステート・フラグやクアッドステート・フラグが必要かどうか等)、 少なくとも注意は払っておくことが重要です。

さらに、 振る舞いA に関する以下の説明は、 おそらくこのユースケースでも依然として有効であると思いますが、 唯一の例外は、 スパース仕様を再定義して、 既にダウンロードされた BLOB に制限することです。 難しいのは、その変更された定義を尊重できるコマンドを作成することです。

この使用例は、 初期のスパース・チェックアウトに関する文書化された前提条件の一部に違反しています(SKIP_WORKTREE としてマークされたファイルは、 作業ツリーに存在するものとしてユーザーに表示されるため)。 この違反は、 スパース・チェックアウトに関連するさまざまな動作がこのユースケースにあまり適していないことを意味する可能性があり、 これを処理するにはドキュメントとコードの両方に調整が必要になる可能性があります。 ただし、 このユースケースは、 いくつかの例外を除いてすべてが高密度(まばらでない)チェックアウトのように動作するという点で、 おそらくサポートする最も単純なモデルでもあります(たとえば、VFS が必要に応じて残りを遅延的に書き込むことがわかっているため、 ブランチ・チェックアウトと switch は書き込む内容が少なくなります)。

一般に公開されて試せる VFS 関連のコードがないため、 そのようなユースケースをテストできる人の数は限られています。

振る舞いC のユースケースに注目する主な理由は、 振る舞いA と 振る舞いB をより適切にサポートするために修正を行う際に、 このユースケースの人々が元の非スパース処理を受けられるように調整する必要がある追加の場所が存在する可能性があるためです。 例については、 ecc7c8841d ("repo_read_index: add config to expect files outside sparse patterns", 2022-02-25)を参照してください。 振る舞いC に注目する 2 番目の理由は、 振る舞いC を利用する人々が自分が 振る舞いB 陣営の一員であると思い込み、 実際の 振る舞いB の人々のために問題を解決するパッチを提案しないようにするためです。

上記の振る舞いの違いを思いっきり単純化すると以下のようになります:

前述したように、 ファイルのサブセットを操作するという単純な考え方にもかかわらず、 このような機能を適切に操作するには、 さまざまなサブコマンドにさまざまな動作変更を加える必要があります。 さまざまな例については、[1,2,3,4,5,6,7,8,9,10] を参照してください。 特に [2] では、スパース・チェックアウト・コンテキストで個別に正しく動作する他のコマンドを単に組み合わせただけでは、 上位レベルのコマンドが正しく動作することを意味しないことが分かります。 場合によってはさらに調整が必要になる場合があります。 したがって、これらの違いを理解することは有益です。

上記により、 振る舞いクラスがいくつあります:

注意: 目的の振る舞いを実現するためのコマンドに応じて、異なるデフォルトがあることに注意してください:

正常に動作する状況では、 スパース仕様は $GIT_DIR/info/sparse-checkout ファイルによって直接指定されます。 ただし、 以下のいくつかの理由で過渡的にそこから逸脱する可能性があります:

上記の最後の項目については、 作業ツリーに存在するファイルの SKIP_WORKTREE ビットが自動的にクリアされることに注意してください。 これはコミット 82386b4496("Merge branch en/present-despite-skipped", 2022-03-09)以降で当てはまります。

ただし、 このような状況は以下の理由により、過渡的なものです:

ステージされてない変更または競合のあるファイルの削除は避けますが、 そうでない場合は、 これらの過渡的な差異を積極的に修正しようとします。 ユーザーがこれらの差異を維持したい場合は、 git sparse-checkout の set または add サブコマンドを実行して、 意図するスパース仕様を反映するべきです。

ただし、 「関連するファイルのサブセット」に限定された履歴に対してクエリを実行する必要がある場合、 そのような過渡的に拡張されたスパース仕様は無視されます。 これには以下のように一組の理由があります:

したがって、 過渡的に拡張された(または制限された)スパース仕様は作業ツリーには適用されますが、 スパース・パターンを使用する履歴クエリには常に適用されません(これに関する初期の議論については、[16] を参照してください。)

作業ツリーに存在する追加フ​​ァイルに基づいて過渡的に拡張された作業ツリーのスパース仕様と同様に、 インデックス内で変更される追加ファイルも考慮する必要があります。 特に、 ユーザーが、(HEAD に関連した、)スパース・パターンにマッチしないファイルへの変更をステージングしており、 そのファイルが作業ツリーには存在しない場合でも、 スパース仕様のファイル部分を考慮する必要があります。 具体的には、 インデックスに関連する問い合わせを実行します(例: git diff --cached [REVISION]、 git diff-index [REVISION]、 git restore --staged --source=REVISION -- PATHS など)。 過渡的に拡張されたスパースは、 振る舞いB ではインデックス操作を履歴と一緒にまとめ、 フルのツリー(full-tree)で操作する傾向があるため、 通常、 インデックスの指定は 振る舞いA でのみ問題になります。

[上記の上 2 つがまだ解決されていないため、 以下はまだ思い付きレベルの話ではあります]

このリストは以前はもっと長かったのですが([1,2,3,4,5,6,7,8,9] を参照)、 私達の鋭意ある取り組みによりだいぶ短くなりました。

sparse-checkout で発生したさまざまなバグを詳しく説明したメール達: