git-update-index - 將工作區中的檔案內容註冊到索引

修改索引。每個提到的檔案都會更新到索引中，並且任何 未合併 或 需要更新 的狀態都會被清除。

另請參閱 git-add[1]，它提供了一種更友好的方式來執行索引上的一些最常見操作。

git update-index 處理它被告知的檔案的方式可以透過各種選項進行修改

--refresh 不會計算新的 sha1 檔案或更新索引以反映模式/內容更改。但它所做的是將檔案的 stat 資訊與索引進行“重新匹配”，以便你可以為未更改但 stat 條目過期的檔案重新整理索引。

例如，在執行 git read-tree 後，你可能希望這樣做，以便將 stat 索引詳細資訊與正確的檔案關聯起來。

--cacheinfo 用於註冊不在當前工作目錄中的檔案。這對於最小化檢出合併很有用。

假設你在路徑上有一個帶有模式和 sha1 的檔案，例如：

--info-only 用於註冊檔案而不將其放入物件資料庫。這對於僅顯示狀態的倉庫很有用。

二者 --cacheinfo 和 --info-only 的行為相似：索引會更新，但物件資料庫不會。當物件在資料庫中但檔案在本地不可用時，--cacheinfo 很有用。--info-only 在檔案可用但你不希望更新物件資料庫時很有用。

--index-info 是一個更強大的機制，它允許你從標準輸入提供多個條目定義，並且專門為指令碼設計。它支援三種輸入格式：

要將更高階段的條目放置到索引中，首先應透過為路徑提供 mode=0 的條目來移除該路徑，然後以第三種格式提供必要的輸入行。

例如，從這個索引開始：

你可以將以下輸入提供給 --index-info：

輸入的第一行將 0 作為模式以移除路徑；SHA-1 只要格式正確就不重要。然後第二行和第三行提供該路徑的階段 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）。

有時使用者會將假定未修改位與跳過工作區位混淆。有關差異的解釋，請參閱下面“跳過工作區位”部分的最後一段。

僅更新和重新整理已檢出的檔案

跳過工作區位可以用一（長）句話定義：告訴 git 在合理可能的情況下避免將檔案寫入工作目錄，並在檔案不在工作目錄中時將其視為未更改。

請注意，並非所有 git 命令都會關注此位，有些只部分支援它。

與跳過工作區位相關的 update-index 標誌和 read-tree 功能早於 git-sparse-checkout[1] 命令的引入，後者提供了一種更簡單的方式來配置和處理跳過工作區位。如果你希望將工作區縮小到只處理倉庫中的一部分檔案，我們強烈建議使用 git-sparse-checkout[1]，而不是底層的 update-index 和 read-tree 原語。

跳過工作區位的主要目的是啟用稀疏檢出，即只存在部分路徑的工作目錄。當設定了跳過工作區位時，Git 命令（例如 switch、pull、merge）將避免寫入這些檔案。然而，在合併或變基期間發生衝突等重要情況下，這些命令有時仍然會寫入這些檔案。Git 命令還會避免將缺少此類檔案視為有意刪除；例如，git add -u 不會為這些檔案暫存刪除，git commit -a 也不會建立刪除它們的提交。

儘管此位看起來與假定未修改位相似，但其目的不同。假定未修改位是為了將檔案留在工作區，但讓 Git 省略檢查其更改並假定檔案未更改（儘管如果它可以在不 stat 檔案的情況下確定其已更改，則可以自由記錄更改）。跳過工作區位告訴 Git 忽略檔案的缺失，在可能的情況下避免使用通常會更新大部分工作目錄的命令（例如 checkout、switch、pull 等）更新它，並且不將其缺失記錄在提交中。請注意，在稀疏檢出（由 git sparse-checkout 或將 core.sparseCheckout 配置為 true 設定）中，如果檔案在索引中被標記為跳過工作區但在工作區中找到，Git 將清除該檔案的跳過工作區位。

此模式專為具有非常大索引的倉庫設計，旨在減少重複寫入這些索引所需的時間。

在此模式下，索引被分成兩個檔案：$GIT_DIR/index 和 $GIT_DIR/sharedindex.<SHA-1>。更改累積在 $GIT_DIR/index（分離索引）中，而共享索引檔案包含所有索引條目並保持不變。

當分離索引中的條目數量達到 splitIndex.maxPercentChange 配置變數（參見 git-config[1]）指定的級別時，分離索引中的所有更改都會被推回共享索引檔案。

每次建立新的共享索引檔案時，如果舊的共享索引檔案的修改時間早於 splitIndex.sharedIndexExpire 配置變數（參見 git-config[1]）指定的時間，則它們將被刪除。

為避免刪除仍在使用的共享索引檔案，每當基於共享索引檔案建立或讀取新的分離索引時，其修改時間都會更新為當前時間。

此快取旨在加速涉及確定未跟蹤檔案的命令，例如 git status。

此功能透過記錄工作區目錄的修改時間（mtime）來工作，然後省略讀取那些修改時間未更改的目錄以及對其中檔案的 stat 呼叫。為此，底層作業系統和檔案系統必須在目錄中新增、修改或刪除檔案時更改目錄的 st_mtime 欄位。

你可以使用 --test-untracked-cache 選項測試檔案系統是否支援此功能。在舊版本的 Git 中，--untracked-cache 選項曾隱式執行此測試，但現在已不再如此。

如果你想啟用（或停用）此功能，使用 core.untrackedCache 配置變數（參見 git-config[1]）比在每個倉庫中使用 git update-index 的 --untracked-cache 選項更容易，特別是如果你想在你使用的所有倉庫中這樣做，因為你可以在你的 $HOME/.gitconfig 中只設置一次此配置變數為 true（或 false），它就會影響你操作的所有倉庫。

當 core.untrackedCache 配置變數更改時，未跟蹤快取將在下次命令讀取索引時新增到索引或從索引中移除；而當使用 --[no-|force-]untracked-cache 時，未跟蹤快取會立即新增到索引或從索引中移除。

在 2.17 版本之前，未跟蹤快取有一個 bug，將目錄替換為指向另一個目錄的符號連結可能導致它錯誤地將 Git 跟蹤的檔案顯示為未跟蹤。參見 git.git 中的“status: add a failing test showing a core.untrackedCache bug”提交。解決此問題的方法是（這可能也適用於未來未發現的其他 bug）：

當涉及未跟蹤快取的內部結構時，此 bug 也已被證明會影響非符號連結情況下用檔案替換目錄的情況，但尚未報告因此導致錯誤的“git status”輸出的案例。

還有一些情況，由 2.17 之前 Git 版本寫入的現有索引會引用不再存在的目錄，這可能導致在“git status”上列印許多“無法開啟目錄”警告。這些是針對現有問題的新警告，這些問題以前被靜默丟棄了。

與上述 bug 一樣，解決方案是臨時執行一次 core.untrackedCache=false 的“git status”以清除殘留的錯誤資料。

此功能旨在加速具有大型工作目錄的倉庫的 Git 操作。

它使 Git 能夠與檔案系統監視器（參見 git-fsmonitor--daemon[1] 和 githooks[5] 的“fsmonitor-watchman”部分）協同工作，檔案系統監視器可以告知 Git 哪些檔案已修改。這使得 Git 可以避免對每個檔案執行 lstat() 來查詢已修改的檔案。

當與未跟蹤快取結合使用時，它可以避免掃描整個工作目錄以查詢新檔案的開銷，從而進一步提高效能。

如果你想啟用（或停用）此功能，使用 core.fsmonitor 配置變數（參見 git-config[1]）比在每個倉庫中使用 git update-index 的 --fsmonitor 選項更容易，特別是如果你想在你使用的所有倉庫中這樣做，因為你可以在你的 $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]）。

使用者經常嘗試使用 assume-unchanged 和 skip-worktree 位來告訴 Git 忽略已跟蹤檔案的更改。但這並不能按預期工作，因為 Git 在執行某些操作時仍然可能根據索引檢查工作區檔案。通常，Git 不提供忽略已跟蹤檔案更改的方法，因此建議採用替代解決方案。

例如，如果你想更改的檔案是某種配置檔案，倉庫可以包含一個示例配置檔案，然後可以將其複製到被忽略的名稱並進行修改。倉庫甚至可以包含一個指令碼，將示例檔案視為模板，自動修改和複製它。

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

Git[1] 套件的一部分