git-update-index - 作業ツリーのファイル内容をインデックスに登録する

インデックスを変更します。指定された各ファイルはインデックスに更新され、*unmerged (未マージ)* または *needs updating (更新が必要)* の状態はクリアされます。

インデックスでの一般的な操作をよりユーザーフレンドリーに行う方法については、git-add[1] も参照してください。

*git update-index* が処理するファイルの動作は、さまざまなオプションを使用して変更できます。

`--refresh` は新しいSHA-1ファイルを計算したり、モード/内容の変更のためにインデックスを最新の状態にしたりはしません。しかし、それが**行う**のは、ファイルのstat情報をインデックスと「再一致」させることです。これにより、変更されていないがstatエントリが古いファイルのインデックスを更新できます。

例えば、statインデックスの詳細を適切なファイルにリンクするために、*git read-tree* の実行後にこれを行いたいでしょう。

`--cacheinfo` は、現在の作業ディレクトリにないファイルを登録するために使用されます。これは最小チェックアウトマージに役立ちます。

パスにモードとSHA-1を持つファイルがあると仮定するには、次のようにします。

`--info-only` は、オブジェクトデータベースに配置せずにファイルを登録するために使用されます。これはステータスのみのリポジトリに役立ちます。

両方の `--cacheinfo` と `--info-only` は同様に動作します。インデックスは更新されますが、オブジェクトデータベースは更新されません。`--cacheinfo` は、オブジェクトがデータベースにあるがファイルがローカルで利用できない場合に役立ちます。`--info-only` は、ファイルが利用可能であるがオブジェクトデータベースを更新したくない場合に役立ちます。

`--index-info` は、標準入力から複数のエントリ定義をフィードできる、より強力なメカニズムであり、スクリプトのために特別に設計されています。以下の3つの形式の入力を受け取ることができます。

より高次のステージエントリをインデックスに配置するには、まずそのパスのmode=0エントリをフィードしてパスを削除し、次に3番目の形式で必要な入力行をフィードする必要があります。

例えば、このインデックスから開始して

以下の入力を `--index-info` にフィードできます。

入力の最初の行は、パスを削除するためにモードとして0をフィードします。SHA-1は適切にフォーマットされていれば問題ありません。次に、2行目と3行目は、そのパスのステージ1とステージ2のエントリをフィードします。上記の後、最終的にはこうなります。

Gitの多くの操作は、ファイルシステムが効率的な `lstat(2)` 実装を持っていることに依存しており、作業ツリーファイルの `st_mtime` 情報から、ファイルの内容がインデックスファイルに記録されたバージョンから変更されているかを安価にチェックできるようにしています。残念ながら、一部のファイルシステムには非効率的な `lstat(2)` があります。お使いのファイルシステムがその一つである場合、変更していないパスに「変更なしと仮定する」ビットを設定することで、Gitにこのチェックを行わせないようにすることができます。パスにこのビットを設定しても、Gitがファイルの内容をチェックして変更されたかどうかを確認するわけではないことに注意してください。これは、Gitがあらゆるチェックを省略し、変更**されていない**と仮定させるものです。作業ツリーのファイルを変更する場合は、変更する前または変更した後に「変更なしと仮定する」ビットを解除することで、明示的にGitにそのことを伝える必要があります。

「変更なしと仮定する」ビットを設定するには、`--assume-unchanged` オプションを使用します。解除するには、`--no-assume-unchanged` を使用します。「変更なしと仮定する」ビットが設定されているファイルを確認するには、`git ls-files -v` (git-ls-files[1] を参照) を使用します。

このコマンドは `core.ignorestat` 設定変数を参照します。これが true の場合、`git update-index paths...` で更新されたパス、およびインデックスと作業ツリーの両方を更新する他のGitコマンド (例: *git apply --index*、*git checkout-index -u*、および *git read-tree -u*) で更新されたパスは、自動的に「変更なしと仮定する」とマークされます。`git update-index --refresh` が作業ツリーファイルがインデックスと一致すると判断した場合、「変更なしと仮定する」ビットは**設定されない**ことに注意してください (「変更なしと仮定する」とマークしたい場合は、`git update-index --really-refresh` を使用してください)。

ユーザーは時々、「assume-unchanged」ビットと「skip-worktree」ビットを混同することがあります。違いの説明については、下記の「Skip-worktree bit」セクションの最後の段落を参照してください。

既にチェックアウトされているファイルのみを更新およびリフレッシュするには

Skip-worktreeビットは、（長い）一文で定義できます。合理的に可能な限り、ファイルを作業ディレクトリに書き込まないようにGitに指示し、ファイルが作業ディレクトリに存在しない場合は変更されていないものとして扱います。

すべてのgitコマンドがこのビットに注意を払うわけではなく、一部は部分的にしかサポートしていないことに注意してください。

update-indexのフラグとread-treeのskip-worktreeビットに関する機能は、git-sparse-checkout[1] コマンドの導入に先行していました。git-sparse-checkout[1] は、skip-worktreeビットを設定および処理するためのより簡単な方法を提供します。作業ツリーをリポジトリ内の一部のファイルのみを扱うように削減したい場合は、低レベルのupdate-indexおよびread-treeプリミティブよりも、git-sparse-checkout[1] の使用を強く推奨します。

skip-worktreeビットの主な目的は、スパースチェックアウトを有効にすることです。つまり、パスの一部のみが存在する作業ディレクトリを持つことです。skip-worktreeビットが設定されている場合、Gitコマンド（`switch`、`pull`、`merge`など）はこれらのファイルの書き込みを避けます。ただし、マージやリベース中の競合など、重要な場合にはこれらのコマンドがそれでもファイルを書き込むことがあります。Gitコマンドは、これらのファイルの不足を意図的な削除として扱わないようにもします。例えば、`git add -u` はこれらのファイルの削除をステージせず、`git commit -a` もそれらを削除するコミットを作成しません。

このビットはassume-unchangedビットと似ていますが、その目的は異なります。assume-unchangedビットは、ファイルを作業ツリーに残しつつ、Gitが変更のチェックを省略し、ファイルが変更されていないと仮定するためのものです（ただし、statせずにファイルが変更されたと判断できる場合は、変更を記録することができます）。skip-worktreeは、ファイルの不在をGitに無視させ、通常作業ディレクトリの大部分を更新するコマンド（例：`checkout`、`switch`、`pull`など）での更新を可能な限り避け、その不在がコミットに記録されないようにします。スパースチェックアウト（`git sparse-checkout` または `core.sparseCheckout` をtrueに設定することでセットアップ）では、ファイルがインデックスでskip-worktreeとしてマークされていても作業ツリーで発見された場合、Gitはそのファイルのskip-worktreeビットをクリアすることに注意してください。

このモードは、非常に大きなインデックスを持つリポジトリ向けに設計されており、これらのインデックスを繰り返し書き込むのにかかる時間を短縮することを目的としています。

このモードでは、インデックスが2つのファイル、$GIT_DIR/index と $GIT_DIR/sharedindex.<SHA-1> に分割されます。変更は$GIT_DIR/index、つまりスプリットインデックスに蓄積され、共有インデックスファイルはすべてのインデックスエントリを含み、変更されません。

スプリットインデックス内のエントリ数が splitIndex.maxPercentChange 設定変数 (git-config[1] を参照) で指定されたレベルに達すると、スプリットインデックス内のすべての変更が共有インデックスファイルにプッシュバックされます。

新しい共有インデックスファイルが作成されるたびに、その変更時刻が splitIndex.sharedIndexExpire 設定変数 (git-config[1] を参照) で指定されたものより古い場合、古い共有インデックスファイルは削除されます。

まだ使用されている共有インデックスファイルを削除しないように、共有インデックスファイルに基づいた新しいスプリットインデックスが作成または読み込まれるたびに、その変更時刻が現在の時刻に更新されます。

このキャッシュは、`git status` のような未追跡ファイルを特定するコマンドの速度を向上させることを目的としています。

この機能は、作業ツリーディレクトリのmtimeを記録し、mtimeが変更されていないディレクトリ内のファイルの読み取りやstat呼び出しを省略することで機能します。これが機能するためには、基盤となるオペレーティングシステムとファイルシステムが、ディレクトリ内のファイルが追加、変更、または削除された場合にディレクトリの `st_mtime` フィールドを変更する必要があります。

ファイルシステムがこれをサポートしているかどうかは、`--test-untracked-cache` オプションでテストできます。以前のGitバージョンでは、`--untracked-cache` オプションが暗黙的にそのテストを実行していましたが、現在はそうではありません。

この機能を有効 (または無効) にしたい場合、各リポジトリで `git update-index` に `--untracked-cache` オプションを使用するよりも、`core.untrackedCache` 設定変数 (git-config[1] を参照) を使用する方が簡単です。特に、使用するすべてのリポジトリでそうしたい場合、`$HOME/.gitconfig` に一度だけ `true` (または `false`) を設定すれば、すべてのリポジトリに影響を与えることができるからです。

`core.untrackedCache` 設定変数が変更された場合、次にコマンドがインデックスを読み込むときに、未追跡キャッシュがインデックスに追加または削除されます。一方、`--[no-|force-]untracked-cache` が使用された場合、未追跡キャッシュは直ちにインデックスに追加または削除されます。

2.17より前では、未追跡キャッシュにバグがあり、ディレクトリを別のディレクトリへのシンボリックリンクで置き換えると、gitによって追跡されているファイルが未追跡として誤って表示される可能性がありました。git.gitへの「status: add a failing test showing a core.untrackedCache bug」コミットを参照してください。その回避策は（そしてこれは将来発見されていない他のバグにも機能する可能性があります）

このバグは、未追跡キャッシュの内部構造に関する限り、シンボリックリンク以外のケースでディレクトリをファイルに置き換える場合にも影響することが示されていますが、これが誤った「git status」出力につながったという報告はありません。

また、Gitバージョン2.17より前に書き込まれた既存のインデックスが、もはや存在しないディレクトリを参照している場合があり、これにより「git status」で多数の「ディレクトリを開けませんでした」という警告が表示される可能性があります。これらは、以前は黙って無視されていた既存の問題に対する新しい警告です。

上記のバグと同様に、解決策は一度だけ `core.untrackedCache=false` を設定して「git status」を実行し、残っている不正なデータを削除することです。

この機能は、大規模な作業ディレクトリを持つリポジトリのgit操作を高速化することを目的としています。

これは、ファイルシステムモニター (git-fsmonitor--daemon[1] および githooks[5] の「fsmonitor-watchman」セクションを参照) と連携して動作し、どのファイルが変更されたかをGitに通知できるようにします。これにより、Gitは変更されたファイルを見つけるためにすべてのファイルをlstat()する必要がなくなります。

未追跡キャッシュと組み合わせて使用すると、作業ディレクトリ全体をスキャンして新しいファイルを探すコストを回避することで、パフォーマンスをさらに向上させることができます。

この機能を有効 (または無効) にしたい場合、各リポジトリで `git update-index` に `--fsmonitor` オプションを使用するよりも、`core.fsmonitor` 設定変数 (git-config[1] を参照) を使用する方が簡単です。特に、使用するすべてのリポジトリでそうしたい場合、`$HOME/.gitconfig` に一度だけ設定変数を設定すれば、すべてのリポジトリに影響を与えることができるからです。

`core.fsmonitor` 設定変数が変更された場合、次にコマンドがインデックスを読み込むときに、ファイルシステムモニターがインデックスに追加または削除されます。`--[no-]fsmonitor` が使用された場合、ファイルシステムモニターは直ちにインデックスに追加または削除されます。

このコマンドは `core.filemode` 設定変数を尊重します。もしあなたのリポジトリが実行可能ビットが信頼できないファイルシステム上にある場合、これを *false* に設定すべきです (git-config[1] を参照)。これにより、コマンドはインデックスに記録されたファイルモードとファイルシステム上のファイルモードが実行可能ビットのみで異なる場合、その差異を無視します。そのような残念なファイルシステムでは、*git update-index --chmod=* を使用する必要があるかもしれません。

同様に、`core.symlinks` 設定変数が *false* に設定されている場合 (git-config[1] を参照)、シンボリックリンクは通常のファイルとしてチェックアウトされ、このコマンドは記録されたファイルモードをシンボリックリンクから通常のファイルに変更しません。

このコマンドは `core.ignorestat` 設定変数を参照します。上記の「"変更なしと仮定する"ビットの使用」セクションを参照してください。

このコマンドは `core.trustctime` 設定変数も参照します。これは、inode変更時刻がGit外部の何か (ファイルシステムクローラーやバックアップシステムが処理済みファイルを示すためにctimeを使用する場合など) によって定期的に変更される場合に役立ちます (git-config[1] を参照)。

未追跡キャッシュ拡張機能は、`core.untrackedCache` 設定変数 (git-config[1] を参照) によって有効にできます。

ユーザーは、追跡されているファイルの変更を無視するようGitに指示するために、assume-unchangedビットとskip-worktreeビットを使用しようとすることがよくあります。これは期待通りに機能しません。なぜなら、Gitは特定の操作を実行する際に、作業ツリーファイルをインデックスに対してチェックする可能性があるからです。一般的に、Gitは追跡されているファイルの変更を無視する方法を提供していないため、代替ソリューションが推奨されます。

例えば、変更したいファイルが何らかの設定ファイルである場合、リポジトリにサンプルの設定ファイルを含め、それを無視される名前にコピーして変更することができます。リポジトリには、サンプルファイルをテンプレートとして扱い、自動的に変更およびコピーするスクリプトを含めることさえできます。

git-config[1], git-add[1], git-ls-files[1]

git[1] スイートの一部