Git

git-sparse-checkout は 2.42.0 で最終更新

名前

git-sparse-checkout - ワーキングツリーを追跡ファイルのサブセットに絞り込む

概要

git sparse-checkout (init | list | set | add | reapply | disable | check-rules) [<options>]

説明

このコマンドは、スパースチェックアウトを作成するために使用されます。これにより、ワーキングツリーはすべての追跡ファイルが存在する状態から、それらのファイルのサブセットのみが存在する状態に変わります。また、どのファイルのサブセットが存在するかを切り替えたり、スパースチェックアウトを取り消して、ワーキングコピーにすべての追跡ファイルが存在する状態に戻したりすることもできます。

ファイルのサブセットは、コーンモード（デフォルト）でディレクトリのリストを提供するか、非コーンモードでパターンのリストを提供することによって選択されます。

スパースチェックアウト中は、他のGitコマンドの動作が少し異なります。例えば、ブランチを切り替えても、スパースチェックアウトのディレクトリ/パターン外のパスは更新されず、git commit -a は、スパースチェックアウトのディレクトリ/パターン外のパスを削除として記録しません。

このコマンドは実験的です。その動作、およびスパースチェックアウトが存在する場合の他のコマンドの動作は、将来的に変更される可能性があります。

コマンド

list: スパースチェックアウトファイル内のディレクトリまたはパターンを記述します。
set: 必要なスパースチェックアウト設定 (core.sparseCheckout、core.sparseCheckoutCone、および index.sparse) がまだ希望の値に設定されていない場合、それを有効にし、set サブコマンドに続く引数のリストからスパースチェックアウトファイルを投入し、ワーキングディレクトリを一致するように更新します。

worktree 内でスパースチェックアウト設定を調整しても、他の worktree のスパースチェックアウト設定が変更されないように、set サブコマンドは、まだ存在しない場合はリポジトリ設定を worktree 固有の設定にアップグレードします。set サブコマンドの引数によって定義されたスパース性は、worktree 固有のスパースチェックアウトファイルに保存されます。詳細については、git-worktree[1] と git-config[1] の extensions.worktreeConfig のドキュメントを参照してください。

--stdin オプションが提供された場合、ディレクトリまたはパターンは、引数からではなく、標準入力から改行区切りのリストとして読み込まれます。

デフォルトでは、入力リストは git ls-tree -d --name-only の出力に一致するディレクトリのリストと見なされます。これには、二重引用符 (") で始まるパス名をCスタイルの引用文字列として解釈することも含まれます。指定されたディレクトリの下にあるすべてのファイル（任意の深さ）はスパースチェックアウトに含まれ、与えられたディレクトリまたはその祖先のいずれかの兄弟ファイルも含まれることに注意してください（詳細については、以下のCONE PATTERN SETを参照）。以前は、これがデフォルトではなく、--cone を指定するか、core.sparseCheckoutCone を有効にする必要がありました。

--no-cone が渡されると、入力リストはパターンのリストと見なされます。このモードには、--sparse-index のような一部のオプションと連携しないなど、いくつかの欠点があります。以下の「非コーンモードの問題点」セクションで説明されているように、このモードの使用は推奨されません。

スパースインデックスを使用するには --[no-]sparse-index オプションを使用します（デフォルトでは使用しません）。スパースインデックスは、スパースチェックアウトの定義により密接に合わせたインデックスのサイズを削減します。これは、git status や git add のようなコマンドで顕著なパフォーマンス上の利点をもたらす可能性があります。この機能はまだ実験中です。一部のコマンドは、この機能と適切に統合されるまで、スパースインデックスを使用すると遅くなる可能性があります。

警告： スパースインデックスを使用するには、外部ツールによって完全に理解されていない方法でインデックスを変更する必要があります。この互換性で問題が発生した場合は、git sparse-checkout init --no-sparse-index を実行して、インデックスをスパースではない状態に書き換えてください。古いバージョンのGitは、スパースディレクトリエントリのインデックス拡張を理解せず、無効になるまでリポジトリとのやり取りに失敗する可能性があります。
add: 追加のディレクトリ（コーンモードの場合）またはパターン（非コーンモードの場合）を含むようにスパースチェックアウトファイルを更新します。デフォルトでは、これらのディレクトリまたはパターンはコマンドライン引数から読み込まれますが、--stdin オプションを使用して標準入力から読み込むこともできます。
reapply: ワーキングツリー内のパスにスパースパターンルールを再適用します。マージやリベースなどのコマンドは、作業を行うためにパスを実体化する可能性があり（例：競合を表示するため）、他のスパースチェックアウトコマンドは個々のファイルをスパース化できない場合があります（例：ステージングされていない変更や競合があるため）。そのような場合、影響を受けるパスをクリーンアップした後（例：競合の解決、変更の取り消しまたはコミットなど）に git sparse-checkout reapply を実行することが理にかなっています。

reapply コマンドは、set コマンドのフラグと同じ意味で --[no-]cone および --[no-]sparse-index フラグを受け取ることもでき、すべてのスパースパスを再指定する必要なく、使用しているスパースモードを変更できます。
disable: core.sparseCheckout 設定を無効にし、ワーキングディレクトリをすべてのファイルを含む状態に戻します。
init: 指定されたパスなしで set のように動作する非推奨のコマンド。将来的に削除される可能性があります。

歴史的に、set は必要なすべての設定を処理せず、init と set の両方を呼び出す必要がありました。両方を呼び出すと、init ステップで最初にほぼすべての追跡ファイル (コーンモードでは無視ファイルも) を削除し、次に set ステップで追跡ファイルの多く (無視ファイルは除く) を追加し直していました。失われたファイルに加えて、この組み合わせのパフォーマンスとUIは劣悪でした。

また、歴史的に、init は既にスパースチェックアウトファイルが存在する場合、実際にはそれを初期化しませんでした。これは、後続の set または add コマンドに渡すパスを記憶せずにスパースチェックアウトに戻ることが可能であったことを意味します。しかし、--cone および --sparse-index オプションは disable コマンドを越えて記憶されなかったため、単なる init を呼び出す簡単な復元方法は有用性が低下しました。
check-rules: スパースルールが1つ以上のパスに一致するかどうかをチェックします。

デフォルトでは、check-rules は標準入力からパスのリストを読み込み、現在のスパースルールに一致するもののみを出力します。入力は1行に1つのパスで構成され、git ls-tree --name-only の出力に一致することが期待されます。これには、二重引用符 (") で始まるパス名がCスタイルの引用文字列として解釈されることも含まれます。

--rules-file フラグを指定して呼び出すと、入力ファイルは現在のスパースチェックアウトルールではなく、にあるスパースチェックアウトルールと照合されます。ファイル内のルールは、git sparse-checkout set --stdin で受け入れられる形式と同じ形式であることが期待されます (特に、改行区切りである必要があります)。

デフォルトでは、--rules-file オプションに渡されるルールは、コーンモードのディレクトリとして解釈されます。--rules-file で非コーンモードのパターンを渡すには、そのオプションと --no-cone オプションを組み合わせます。

-z フラグを指定して呼び出すと、標準入力からのパスの入力形式と出力パスは \0 で終端され、引用符で囲まれません。これは、--rules-file オプションで渡されるルールの形式には適用されないことに注意してください。

例

git sparse-checkout set MY/DIR1 SUB/DIR2: MY/DIR1/ と SUB/DIR2/ の下のすべてのファイル（任意の深さ）がワーキングコピーに存在するようにスパースチェックアウトを変更します（MY/ および SUB/ 直下、およびトップレベルディレクトリのすべてのファイルも含む）。既にスパースチェックアウト中の場合は、ワーキングコピーに存在するファイルをこの新しい選択に変更します。このコマンドは、追跡ファイルも無視されていない未追跡ファイルも存在しなくなったディレクトリ内のすべての無視ファイルを削除することにも注意してください。
git sparse-checkout disable: ワーキングディレクトリにすべてのファイルを再投入し、スパースチェックアウトを無効にします。
git sparse-checkout add SOME/DIR/ECTORY: SOME/DIR/ECTORY/ の下のすべてのファイル（任意の深さ）をスパースチェックアウトに追加し、SOME/DIR/ の直下と SOME/ の直下のすべてのファイルも追加します。このコマンドを使用する前に、既にスパースチェックアウト中である必要があります。
git sparse-checkout reapply: コマンドが、選択されたスパースディレクトリを尊重しない方法でワーキングツリーを更新する可能性があります。これは、Git外部のツールがファイルを書き込むことによって発生したり、特殊なケース（マージ/リベース時の競合など）や一部のコマンドがスパースチェックアウトを完全にサポートしていなかった（例：古いrecursiveマージバックエンドは限られたサポートしかなかった）ため、Gitコマンドに影響を与えることさえあります。このコマンドは、既存のスパースディレクトリ仕様を再適用して、ワーキングディレクトリを一致させます。

内部 — スパースチェックアウト

"スパースチェックアウト" は、ワーキングディレクトリをスパースに展開することを可能にします。これは、Git にワーキングディレクトリ内のファイルが注目する価値があるかどうかを伝えるために、スキップワーキングツリービット（git-update-index[1] を参照）を使用します。スキップワーキングツリービットが設定され、ファイルがワーキングツリーに存在しない場合、その不在は無視されます。Git はこれらのファイルの内容を展開するのを避けるため、スパースチェックアウトは、多くのファイルがあるリポジトリで作業する際に、現在のユーザーにとって重要なファイルが少ない場合に役立ちます。

$GIT_DIR/info/sparse-checkout ファイルは、スキップワーキングツリー参照ビットマップを定義するために使用されます。Git がワーキングディレクトリを更新すると、このファイルに基づいてインデックス内のスキップワーキングツリービットを更新します。ファイル内のパターンに一致するファイルはワーキングディレクトリに表示され、残りは表示されません。

内部 — 非コーンモードの問題点

set および add サブコマンドによって投入される $GIT_DIR/info/sparse-checkout ファイルは、.gitignore ファイルと同じ構文を使用した多数のパターン（1行に1つ）として定義されます。コーンモードでは、これらのパターンはディレクトリに一致するように制限されます（そしてユーザーは常にディレクトリ名のみを提供または参照する必要がありますが）、非コーンモードでは任意の gitignore 形式のパターンが許可されます。非コーンモードで完全な gitignore 形式のパターンを使用すると、いくつかの欠点があります。

根本的に、様々なワーキングツリー更新プロセス（プル、マージ、リベース、スイッチ、リセット、チェックアウトなど）が O(N*M) のパターンマッチングを必要とします。ここで N はパターンの数、M はインデックス内のパスの数です。これはスケールしません。
スケーリングの問題を回避するには、先頭のディレクトリ名やグロブを指定してパターンの数を制限する必要があります。
コマンドラインでグロブを渡すのは、ユーザーがグロブを引用符で囲むのを忘れて、シェルがすべてのマッチするファイルに展開してそれらをすべて個別にsparse-checkout set/addに渡してしまう可能性があるため、エラーが発生しやすいです。これは、例えば「git grep — *.c」のような場合でも問題になる可能性がありますが、grep/log/statusでの間違いはすぐに出力に現れます。sparse-checkoutの場合、間違いはsparse-checkoutコマンドが実行されたときに記録され、ユーザーが後でブランチを切り替えたり、リベースやマージしたりするまで問題にならない可能性があるため、ユーザーのエラーとそれが気づかれるまでの間に遅延が生じます。
前の項目に関連して、スパースチェックアウトには add サブコマンドがありますが、remove サブコマンドはありません。たとえ remove サブコマンドが追加されたとしても、意図せず引用符を外し忘れたグロブの取り消しは、「削除しすぎる」リスクを伴います。なぜなら、意図しない追加の前に含まれていたエントリを削除してしまう可能性があるからです。
非コーンモードは、何を**含めるか**を選択するために gitignore スタイルのパターンを使用します（否定パターンを除く）。一方、.gitignore ファイルは、何を**除外するか**を選択するために gitignore スタイルのパターンを使用します（否定パターンを除く）。gitignore スタイルのパターンに関するドキュメントは、通常、一致するかしないかという観点ではなく、ユーザーが「除外したい」ものについて語っています。これは、ユーザーが望む動作を得るためにスパースチェックアウトパターンを指定する方法を学ぼうとするときに混乱を招く可能性があります。
何らかの「特殊なパスパターンマッチング」を提供したい他のすべてのgitサブコマンドはpathspecsを使用しますが、sparse-checkoutの非コーンモードはgitignoreパターンを使用しており、一貫性がありません。

「正しい」振る舞いが不明瞭なエッジケースがあります。2つの例：

First, two users are in a subdirectory, and the first runs
   git sparse-checkout set '/toplevel-dir/*.c'
while the second runs
   git sparse-checkout set relative-dir
Should those arguments be transliterated into
   current/subdirectory/toplevel-dir/*.c
and
   current/subdirectory/relative-dir
before inserting into the sparse-checkout file?  The user who typed
the first command is probably aware that arguments to set/add are
supposed to be patterns in non-cone mode, and probably would not be
happy with such a transliteration.  However, many gitignore-style
patterns are just paths, which might be what the user who typed the
second command was thinking, and they'd be upset if their argument
wasn't transliterated.

Second, what should bash-completion complete on for set/add commands
for non-cone users?  If it suggests paths, is it exacerbating the
problem above?  Also, if it suggests paths, what if the user has a
file or directory that begins with either a '!' or '#' or has a '*',
'\', '?', '[', or ']' in its name?  And if it suggests paths, will
it complete "/pro" to "/proc" (in the root filesystem) rather than to
"/progress.txt" in the current directory?  (Note that users are
likely to want to start paths with a leading '/' in non-cone mode,
for the same reason that .gitignore files often have one.)
Completing on files or directories might give nasty surprises in
all these cases.

過度の柔軟性により、他の拡張機能が実質的に実用的でなくなりました。--sparse-indexは非コーンモードではおそらく不可能でしょう。たとえ何らかの方法で実現可能であったとしても、実装にははるかに多くの作業が必要であり、実際には遅すぎたかもしれません。部分クローンとスパースチェックアウトの間に結合を追加するといういくつかのアイデアも、より制限されたパスのセットでのみ実用的です。

これらすべての理由により、非コーンモードは非推奨です。コーンモードの使用に切り替えてください。

内部 — コーンモードの処理

デフォルトの「コーンモード」では、含めるディレクトリのみを指定できます。指定されたディレクトリの下にあるすべてのパスが含まれ、先行するディレクトリ（トップレベルディレクトリを含む）の直下にあるすべてのパスも含まれます。したがって、ディレクトリ Documentation/technical/ を指定した場合、スパースチェックアウトには以下が含まれます。

トップレベルディレクトリ内のすべてのファイル
Documentation/直下のすべてのファイル
Documentation/technical/ の下の任意の深さのすべてのファイル

また、コーンモードでは、ディレクトリが指定されていない場合でも、トップレベルディレクトリ内のファイルが含まれます。

コーンモードでスパースチェックアウトパターンを変更すると、Gitはスパースチェックアウトコーン内にない追跡ディレクトリをそれぞれ検査し、未追跡ファイルが含まれているかどうかを確認します。これらのファイルがすべて.gitignoreパターンによって無視されている場合、ディレクトリは削除されます。そのディレクトリ内の未追跡ファイルが無視されていない場合、そのディレクトリ内では削除は行われず、警告メッセージが表示されます。これらのファイルが重要な場合、スパースチェックアウトの定義をリセットしてそれらを含め、git addおよびgit commitを使用してそれらを保存し、残りのファイルを手動で削除して、Gitが最適に動作できるようにします。

ディレクトリが内部でスパースチェックアウトの完全パターンセットのサブセットに変換される方法については、「内部 — コーンパターンセット」セクションも参照してください。

内部 — 完全パターンセット

完全なパターンセットでは、任意のパターンマッチングと複雑な包含/除外ルールが可能です。これらは、インデックスを更新する際に O(N*M) のパターンマッチングを引き起こす可能性があり、ここで N はパターンの数、M はインデックス内のパスの数です。このパフォーマンスの問題に対処するため、core.sparseCheckoutCone が有効な場合、より制限されたパターンセットが許可されます。

スパースチェックアウトファイルは .gitignore ファイルと同じ構文を使用します。詳細については、gitignore[5] を参照してください。ただし、ここではパターンは通常、除外するファイルではなく、含めるファイルを選択するために使用されます。（しかし、gitignore形式のパターンは ! で始まるパターンによって定義される否定を持つため、含めないファイルを選択することもできるため、少し混乱することがあります。）

例えば、すべてを選択し、その後ファイル unwanted を削除する場合（これにより、unwanted という名前のファイルを除いて、すべてのファイルがワーキングツリーに表示されます）：

git sparse-checkout set --no-cone '/*' '!unwanted'

これらのパターンは $GIT_DIR/info/sparse-checkout にそのまま配置されるため、この時点でのそのファイルの内容は次のようになります。

/*
!unwanted

スパースチェックアウトで使用される gitignore 形式のパターンについてさらに学ぶには、git-read-tree[1] の「スパースチェックアウト」セクションも参照してください。

内部 — コーンパターンセット

コーンモードでは、ディレクトリのみが受け入れられますが、それらは完全なパターンセットで使用されるのと同じgitignore形式のパターンに変換されます。これらのモードで使用される特定のパターンを、次の2つのタイプのいずれかとして参照します。

再帰的: ディレクトリ内のすべてのパスが含まれます。
親: ディレクトリ内の直下のすべてのファイルが含まれます。

コーンモードでは常にトップレベルのファイルが含まれるため、ディレクトリが指定されていない状態で git sparse-checkout set を実行すると、トップレベルディレクトリが親パターンとして追加されます。この時点では、スパースチェックアウトファイルには次のパターンが含まれます。

/*
!/*/

これは「トップレベルディレクトリ直下のすべてを含めるが、それより下のレベルは何も含めない」という意味です。

コーンモードでは、git sparse-checkout set サブコマンドはディレクトリのリストを受け取ります。コマンド git sparse-checkout set A/B/C はディレクトリ A/B/C を再帰パターンとして設定し、ディレクトリ A および A/B は親パターンとして追加されます。結果として生成されるスパースチェックアウトファイルは次のようになります。

/*
!/*/
/A/
!/A/*/
/A/B/
!/A/B/*/
/A/B/C/

ここでは順序が重要であり、否定パターンはファイルの下位に現れる肯定パターンによって上書きされます。

core.sparseCheckoutCone が明示的に false に設定されていない限り、Git はスパースチェックアウトファイルを解析し、これらのタイプのパターンを期待します。パターンが一致しない場合、Git は警告を出します。パターンが期待される形式に一致する場合、Git はスパースチェックアウトでの包含を計算するために、より高速なハッシュベースのアルゴリズムを使用します。一致しない場合、設定に関わらず、Git は core.sparseCheckoutCone が false であるかのように動作します。

コーンモードの場合、完全なパターンが $GIT_DIR/info/sparse-checkout ファイルに書き込まれるという事実にもかかわらず、git sparse-checkout list サブコマンドは再帰パターンを定義するディレクトリをリストアップします。上記の例のスパースチェックアウトファイルの場合、出力は次のようになります。

$ git sparse-checkout list
A/B/C

core.ignoreCase=true の場合、パターンマッチングアルゴリズムは大文字と小文字を区別しないチェックを使用します。これにより、git sparse-checkout set コマンドにおける大文字と小文字が一致しないファイル名が修正され、ワーキングディレクトリ内の期待されるコーンが反映されます。

内部 — サブモジュール

リポジトリに1つ以上のサブモジュールが含まれている場合、サブモジュールは git submodule コマンドとのやり取りに基づいて展開されます。具体的には、git submodule init -- はのサブモジュールが存在することを保証し、git submodule deinit [-f] -- はのサブモジュールのファイル（未追跡ファイル、コミットされていない変更、プッシュされていない履歴を含む）を削除します。スパースチェックアウトがワーキングツリーからファイルを削除してもインデックスにエントリを残すのと同様に、非初期化されたサブモジュールはワーキングディレクトリから削除されますが、インデックスにはエントリが残ります。

サブモジュールにはプッシュされていない変更や未追跡ファイルが存在する可能性があるため、それらを削除するとデータ損失につながる可能性があります。したがって、スパース包含/除外ルールを変更しても、既にチェックアウトされているサブモジュールがワーキングコピーから削除されることはありません。言い換えれば、サブモジュールを削除または追加するブランチ間で切り替える場合でも、checkout がサブモジュールを自動的に削除または初期化しないのと同様に、sparse-checkout を使用して「関心のある」ファイルの範囲を縮小または拡大しても、サブモジュールが自動的に非初期化または初期化されることはありません。

さらに、上記の事実が意味するのは、「追跡されている」ファイルがワーキングコピーに存在しない複数の理由があるということです。スパースチェックアウトによるスパースパターン適用、およびサブモジュールの初期化状態です。したがって、ワーキングコピー内の追跡ファイルに対して動作する git grep のようなコマンドは、これらの制限のいずれかまたは両方によって限定される結果を返す可能性があります。

参照

git-read-tree[1] gitignore[5]

git[1] スイートの一部

セットアップと設定

プロジェクトの取得と作成

基本的なスナップショット作成

ブランチとマージ

プロジェクトの共有と更新

調査と比較

パッチ適用

デバッグ

Eメール

外部システム

サーバー管理

ガイド

管理

内部コマンド (Plumbing Commands)

名前

概要

説明