SYNOPSIS

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

DESCRIPTION

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

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

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

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

COMMANDS

list

スパース・チェックアウト・ファイルにディレクトリ達またはパターン達を記述します。

set

必要なスパース・チェックアウト構成設定(core.sparseCheckout と core.sparseCheckoutCone と`index.sparse`)がまだ目的の値に設定されていない場合は有効にし、 set サブコマンドに続く引数のリストからスパース・チェックアウト・ファイルに入力し、それにマッチするよう作業ディレクトリを更新します。

ワークツリー内のスパース・チェックアウト設定を調整しても、他のワークツリーのスパース・チェックアウト設定が変更されないようにするために、 set サブコマンドは、ワークツリー固有の設定がまだ存在しない場合は、それを使用するようにあなたのリポジトリ設定をアップグレードします。 set サブコマンドへの引数によって定義されたスパース性は、ワークツリー固有のスパース・チェックアウト・ファイル(worktree-specific sparse-checkout file)に格納されます。 詳細については、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 などの一部のオプションが機能し無い等、多くの欠点があります。 下記「Non-cone Problems」セクションで説明されているように、使用はお勧めしません。

--[no-]sparse-index オプションを使用して、 スパース・インデックスを使用します(デフォルトでは使用しません)。 スパース・インデックスは、 インデックスのサイズを縮小して、スパース・チェックアウトの定義により近づけます。 これにより、 git status や git add などのコマンドのパフォーマンスが大幅に向上します。 この機能はまだ実験段階です。 一部のコマンドは、機能に適切に統合されるまで、 スパース・インデックスを使用すると遅くなる可能性があります。

Warning
 スパースインデックスを使用するには、外部ツールでは完全には理解できない方法でインデックスを変更する必要があります。 この互換性に問題がある場合は、 git sparse-checkout init --no-sparse-index を実行して、インデックスがまばらにならないように書き換えます。 古いバージョンのGitは、スパースディレクトリエントリのインデックス拡張機能を理解せず、それが無効になるまでリポジトリとのやり取りに失敗する可能性があります。
add

スパース・チェックアウト・ファイルを更新して、 追加のディレクトリ(コーン・モードの場合)またはパターン(非コーン・モードの場合)を含めます。 デフォルトでは、これらのディレクトリまたはパターンはコマンドライン引数から読み取られますが、 --stdin オプションを使用して stdin から読み取ることができます。

reapply

作業ツリーのパスにスパースパターンルールを再適用します。 マージやリベースなどのコマンドは、作業を行うためのパスを具体化でき(たとえば、競合を表示するため)ますが、他のスパースチェックアウトコマンドは、個々のファイルをスパース化できない場合があります(たとえば、ステージングされていない変更や競合があるため)。 このような場合、影響を受けるパスをクリーンアップした後、(たとえば、競合の解決、変更の取り消しまたはコミットなどの)後で git sparse-checkout reapply を実行するのが理にかなっています。

reapply コマンドは --[no-]cone や --[no-]sparse-index フラグも使用できます。これは、 set コマンドのフラグと同一の意味で、 これにより、あなたは全てのスパース・パス(sparsity paths)を再指定すること無く、スパース・モードを変更できます。

disable

core.sparseCheckout 構成設定を無効にし、すべてのファイルを含めるように作業ディレクトリを復元(restore)します。

init

パスが指定されていない「set」のように動作する非推奨のコマンド。 将来削除される可能性があります。

かつて set は必要なすべての構成設定を処理していませんでした。 つまり、 init と set の両方を呼び出す必要がありました。 両方を呼び出すと、最初に init ステップでほぼすべての追跡ファイルが削除され(コーン・モードでは無視されたファイル(ignored files)も含めて)、 次に set ステップで追跡ファイルの多くが追加されます(ただし、無視されたファイル(ignored files)は含まれません)。 ファイルが失われるだけでなく、この組み合わせのパフォーマンスと UI も貧弱でした。

また、かつては、 スパース・チェックアウト・ファイルが既に存在する場合、 init は実際にはそれを初期化しませんでした。 これは、後続の set または add コマンドに渡すパスを覚えていなくても、 スパース・チェックアウトに戻ることができることを意味していました。 ただし、 --cone オプションと --sparse-index オプションは、 disable コマンドまでまたがって記憶される訳では無いため、 単純な init を呼び出す簡単な復元の有用性が低下しました。

check-rules

スパースのルール(sparsity rules)が 1 つ以上のパスにマッチするかどうかチェックします。

デフォルトでは、 check-rules は stdin からパスのリストを読み取り、 現在のスパースのルール(sparsity rules)にマッチするパスのみを出力します。 入力は一行につき一つのパスで構成され、 二重引用符 (") で始まるパス名は C 言語スタイルのクォートされた文字列として解釈されることを含めて、 git ls-tree --name-only の出力と一致します。

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

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

-z フラグを指定して呼び出すと、出力パスと同様に、 stdin に入力されるパスの形式は \0 で終了し、クォートされません。 これは、--rules-file オプションで渡されるルールの形式には適用されないことに注意してください。

EXAMPLES

git sparse-checkout set MY/DIR1 SUB/DIR2

作業コピーに存在する MY/DIR1/ および SUB/DIR2/ の下のすべてのファイル(任意の深さ)(加えて MY/ や SUB/ 直下と、トップレベル・ディレクトリのすべてのファイル)を使用して、スパース チェックアウトに変更します。 すでにスパース・チェックアウトである場合は、作業コピーに存在するファイルをこの新しい選択に変更します。 注意: このコマンドは、追跡中のファイルまたは、無視されていない追跡されていない(non-ignored-untracked)ファイルが存在しなくなったディレクトリ内のすべての無視されたファイル(ignored files)も削除することに注意してください。

git sparse-checkout disable

スパース・チェックアウトを無効にして、 作業ディレクトリにすべてのファイルを再入力します。

git sparse-checkout add SOME/DIR/ECTORY

SOME/DIR/ECTORY/ の下(任意の深さ)にあるすべてのファイルをスパース・チェックアウトに追加し、 SOME/DIR/ の直下と SOME/ の直下にあるすべてのファイルも追加します。 このコマンドを使用する前に、スパース・チェックアウトにしておく必要があります。

git sparse-checkout reapply

コマンドが、 選択されたスパース・ディレクトリを尊重しない方法で作業ツリーを更新する可能性があります。 これは、Git の外部のツールがファイルを書き込むことで発生したり、 また、(マージ/リベース時に競合が発生するなどの)特殊なケースや一部のコマンドがスパース・チェックアウトを完全にサポートしていないために Git コマンドに影響を与えるたりする可能性があります(たとえば、古い「recursive」(再帰的)マージ・バックエンドのサポートは限定的でした)。 このコマンドは、既存のスパース・ディレクトリの指定を再適用して、作業ディレクトリを一致させます。

INTERNALS — SPARSE CHECKOUT

「スパース・チェックアウト」(sparse checkout;疎らなチェックアウト)を使用すると、 作業ディレクトリを疎らに設定できます。 これは、skip-worktree ビット (git-update-index(1) を参照) を使用して、作業ディレクトリ内のファイルを調べる価値があるかどうかを Git に伝えます。 skip-worktree ビットが設定されていて、 ファイルが作業ツリーに存在しない場合、その不在は無視されます。 Git はこれらのファイルの内容を作業ディレクトリに入力することを回避します。これにより、多くのファイルを含むリポジトリで作業する場合にはスパース・チェックアウトが役に立ちますが、現在のユーザーにとってほとんど重要では無いものです。

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

INTERNALS — NON-CONE PROBLEMS

set や add サブコマンドによって入力される $GIT_DIR/info/sparse-checkout ファイルは、 .gitignore ファイルと同じ構文を使用して(1行に1つの)一連のパターンとして定義されます。 コーン・モードでは、 これらのパターンは一致するディレクトリに制限されます(ユーザーはディレクトリ名を指定または表示するだけで済みます)。一方、非コーン・モードでは、任意の gitignore スタイルのパターンが許可されます。 非コーン・モードで完全な gitignore スタイルのパターンを使用すると、 以下のようないくつかの欠点があります:

  • 基本的に、さまざまなワークツリー更新プロセス(pull, merge, rebase, switch, reset, checkout, 等)で O(N*M) 回のパターン・マッチングが必要になります。ここで、N はパターンの数、M はインデックス内のパスの数です。これはスケーリングが不十分です。

  • スケーリングの問題を回避するには、先頭のディレクトリ名またはグロブを指定してパターンの数を制限する必要があります。

  • コマンドラインでグロブを渡すとエラーが発生しやすくなります。ユーザーがグロブをクォートするのを忘れる可能性があるため、シェルがそれをすべての一致するファイルに展開し、それらすべてを個別にスパース・チェックアウト set/add に渡す原因となります。 これは、例えば git grep -- *.c でも問題になる可能性がありますが、 grep/log/status での間違いは即座に出力が得られます。 スパース・チェックアウトでは、間違いはスパース・チェックアウト・コマンドの実行時に記録され、後でユーザーがブランチ切り替えまたはリベースまたはマージを行うまで問題にならない可能性があるため、ユーザーのエラーと、ユーザーがそれをキャッチする機会、またはユーザにそれを通知する機会、までに遅延が生じます。

  • 先の項目に関連して、スパース・チェックアウトには add サブコマンドがありますが、 remove サブコマンドはありません。 remove サブコマンドが追加された場合、クォートされていない偶発的なグロブを元に戻すと、偶発的な追加の前に含まれていたエントリが削除される可能性があるため、「削除しすぎ」のリスクがあります。

  • 非コーン・モード(non-cone mode)では gitignore スタイルのパターンを使用して「含める」(否定パターンを除く)ものを選択しますが、 .gitignore ファイルは gitignore スタイルのパターンを使用して「除外するもの」(否定パターンを除く)を選択します。 gitignore スタイルのパターンに関するドキュメントは通常、 一致または不一致の観点からではなく、 ユーザーが何を「除外」したいかについて述べています。 これは、 スパース・チェックアウト・パターンを指定して目的の動作を取得する方法を学習しようとしているユーザーにとっては混乱を招く可能性があります。

  • ある種の「特別なパス・パターン・マッチング」を提供したい他のすべての git サブコマンドは pathspecs を使用しますが、 スパース・チェックアウトの非コーン・モードは gitignore パターンを使用するため、一貫性がありません。

  • 「正しい」振る舞いが不明確な境界ギリギリのケース(edge cases)があります。 以下に例を2つ挙げます:

    • 最初の例は、 あるサブディレクトリに 2 人のユーザーがいて、 最初のユーザーが以下を実行します 

      `git sparse-checkout set '/toplevel-dir/*.c'`

      ここで、 2人目のユーザーが以下を実行します

      `git sparse-checkout set relative-dir`

      上記2つの引数は以下のように変換されるべきでしょうか？

      `current/subdirectory/toplevel-dir/*.c`

      と

      `current/subdirectory/relative-dir`

      というのも、 最初のコマンドを入力したユーザーは、 set/add の引数が非円錐(non-cone)モードのパターンであることを認識しており、おそらくこのような変換には満足しないでしょう。 けれども、多くの gitignore スタイルのパターンは単なるパスであり、2 番目のコマンドを入力したユーザーが考えていたものである可能性があり、引数が変換されていないと動揺することでしょう。

    • ２つ目の例は、非コーンのユーザーの set/add コマンドの bash補完で補完させる必要があるのは何でしょうか？という問題です。 パスが提案されている場合、上記の問題を悪化させていませんか？ また、パスが提案されている場合、ユーザーのファイルやディレクトリが ! や # で始まっていたり、その名前に * や \ や ? や [ や ] が含まれていたらどうなるでしょう？ そしてまた、パスを提案する場合、現在のディレクトリの /progress.txt ではなく、 /pro を (ルート・ファイルシステムの) /proc に補完しますか？ (.gitignore ファイルにあることが多いのと同じ理由で、ユーザーは非コーン・モードで先頭の / でパスを開始する可能性が高いことに注意してください。) これらすべての場合で、ファイルまたはディレクトリを補完すると、厄介なサプライズが生じる可能性があります。

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

これらすべての理由から、 非コーン・モードは推奨されません。 コーン・モードを使用するように切り替えてください。

INTERNALS — CONE MODE HANDLING

デフォルトの「コーン・モード」では、含めるディレクトリのみを指定できます。 指定されたディレクトリについては、そのディレクトリの下のすべてのパスが含まれ、先頭のディレクトリ (最上位ディレクトリを含む) のすぐ下のパスも含まれます。 したがって、ディレクトリ Documentation/technical/ を指定した場合、スパース・チェックアウトには以下が含まれます:

  • 最上位ディレクトリ内のすべてのファイル

  • Documentation/ 直下のすべてのファイル

  • Documentation/technical/ の下の任意の深さのすべてのファイル

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

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

ディレクトリがフード(hood)の下でスパース・チェックアウトのフル・パターン・セットのサブセットに変換される方法については、「Internals — Cone Pattern Set」セクションも参照してください。

INTERNALS — FULL PATTERN SET

フルパターンセットにより、任意のパターンの一致と複雑な包含/除外ルールが可能になります。 これらにより、インデックスを更新するときに 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) の「Sparse Checkout」セクションも参照してください。

INTERNALS — CONE PATTERN SET

コーン・モードでは、ディレクトリのみが受け入れられますが、完全なパターン・セットで使用されるのと同じ gitignore スタイルのパターンに変換されます。 私達はその際に使用される特殊なパターンを2つのタイプに分類しています:

  1. 再帰: (recursive)ディレクトリ内のすべてのパスが含まれます

  2. 親: (parent)ディレクトリ直下のすべてのファイルが含まれます。

コーン・モードでは常にトップレベルにファイルが含まれるため、 ディレクトリを指定せずに 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 コマンドのファイル名が一致しない状況が修正され、作業ディレクトリに期待される円錐(cone)が反映されます。

INTERNALS — SUBMODULES

あなたのリポジトリに1つ以上のサブモジュールが含まれている場合、サブモジュールは git submodule コマンドとの相互作用に基づいて入力されます。 具体的には、 git submodule init -- <path> は <path> のサブモジュールが存在することを確認し、 git submodule deinit [-f] -- <path> は <path> のサブモジュールのファイルを削除します(追跡されていないファイル、コミットされていない変更、プッシュされていない履歴を含む)。sparse-checkoutが作業ツリーからファイルを削除するが、インデックスにエントリを残す方法と同様に、初期化されていないサブモジュールは作業ディレクトリから削除されますが、インデックスにはエントリがあります。

サブモジュールにはプッシュされていない変更または追跡されていないファイルがある可能性があるため、それらを削除するとデータが失われる可能性があります。 したがって、スパース 包含/除外 ルールを変更しても、すでにチェックアウトされているサブモジュールが作業コピーから削除されることはありません。 別の言い方をすれば、サブモジュールを削除または追加するブランチを切り替えても、 checkout によってサブモジュールが自動的に削除または初期化されないのと同様に、 sparse-checkout を使用して「興味深い」ファイルの範囲を縮小または拡大してもサブモジュールの自動的な非初期化または初期化は発生しません。

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

SEE ALSO

git-read-tree(1) gitignore(5)

GIT

Part of the git(1) suite