簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-pack-objects 最後更新於 2.49.0

名稱

git-pack-objects - 建立物件的打包歸檔

概要

git pack-objects [-q | --progress | --all-progress] [--all-progress-implied]
	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
	[--local] [--incremental] [--window=<n>] [--depth=<n>]
	[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
	[--cruft] [--cruft-expiration=<time>]
	[--stdout [--filter=<filter-spec>] | <base-name>]
	[--shallow] [--keep-true-parents] [--[no-]sparse]
	[--name-hash-version=<n>] < <object-list>

描述

從標準輸入讀取物件列表，並將一個或多個具有指定基本名稱的打包歸檔寫入磁碟，或將打包歸檔寫入標準輸出。

打包歸檔是一種在兩個倉庫之間高效傳輸一組物件的方式，也是一種訪問高效的歸檔格式。在打包歸檔中，一個物件要麼作為壓縮的整體儲存，要麼作為與其他一些物件的差異儲存。後者通常被稱為增量（delta）。

打包歸檔格式（.pack）被設計為自包含的，以便無需任何額外資訊即可解包。因此，增量所依賴的每個物件都必須存在於包中。

將生成一個包索引檔案（.idx），以便快速、隨機訪問包中的物件。將索引檔案（.idx）和打包歸檔（.pack）都放在 $GIT_OBJECT_DIRECTORY（或 $GIT_ALTERNATE_OBJECT_DIRECTORIES 中的任何目錄）的 pack/ 子目錄中，Git 就可以從包歸檔中讀取資料。

git unpack-objects 命令可以讀取打包歸檔並將其包含的物件擴充套件為“一檔案一物件”格式；智慧拉取（smart-pull）命令通常在它們的對等方為了高效網路傳輸而即時建立包時執行此操作。

選項

base-name

寫入一對檔案（.pack 和 .idx），使用 <base-name> 確定建立的檔名。使用此選項時，一對中的兩個檔案將寫入 <base-name>-<SHA-1>.{pack,idx} 檔案。<SHA-1> 是基於包內容的雜湊值，並寫入到命令的標準輸出。

--stdout

將包內容（本應寫入 .pack 檔案的內容）輸出到標準輸出。

--revs

從標準輸入讀取修訂引數，而不是單個物件名稱。修訂引數的處理方式與 git rev-list 使用 --objects 標誌時的 commit 引數來構建其輸出物件列表的方式相同。結果列表中的物件將被打包。除了修訂版本，--not 或 --shallow <SHA-1> 行也接受。

--unpacked

這意味著 --revs。當處理從標準輸入讀取的修訂引數列表時，將打包的物件限制為尚未打包的物件。

--all

這意味著 --revs。除了從標準輸入讀取的修訂引數列表外，假裝指定了 refs/ 下的所有引用以包含在內。

--include-tag

如果它們引用的物件被包含在生成的包檔案中，則包含未請求的註解標籤。這對於向原生 Git 客戶端傳送新標籤很有用。

--stdin-packs

從標準輸入讀取包檔案的基本名稱（例如，pack-1234abcd.pack），而不是物件名稱或修訂引數。生成的包包含所有列入的包（不以 ^ 開頭的）中列出的所有物件，但不包括任何在排除的包（以 ^ 開頭的）中列出的物件。

與 --revs 或暗示 --revs 的選項（例如 --all）不相容，但 --unpacked 除外，它是相容的。

--cruft

將不可達物件打包到單獨的“cruft”包中，透過 .mtimes 檔案的存在來表示。通常由 git repack --cruft 使用。呼叫者提供一個包名稱列表，並指示哪些包將保留在倉庫中，以及哪些包將被刪除（由 - 字首指示）。cruft 包的內容是所有不包含在倖存包中的物件，這些物件尚未超過寬限期（參見下面的 --cruft-expiration），或者已經超過寬限期，但可以從尚未超過寬限期的其他物件訪問。

當輸入列表包含所有可達物件的包（並將所有其他包列為待刪除）時，相應的 cruft 包將包含所有不可達物件（mtime 新於 --cruft-expiration 的）以及任何 mtime 早於 --cruft-expiration 的不可達物件，但這些物件可以從 mtime 新於 --cruft-expiration 的不可達物件中訪問）。

與 --unpack-unreachable、--keep-unreachable、--pack-loose-unreachable、--stdin-packs 以及其他暗示 --revs 的選項不相容。

--cruft-expiration=<approxidate>

如果指定，mtime 早於 <approxidate> 的物件將從 cruft 包中刪除。如果未指定（並且給出了 --cruft），則不會刪除任何物件。

--window=<n>
--depth=<n>

這兩個選項影響包中物件使用增量壓縮的儲存方式。物件首先根據型別、大小和可選的名稱進行內部排序，並與 --window 內的其他物件進行比較，以檢視使用增量壓縮是否可以節省空間。--depth 限制了最大增量深度；使其過深會影響解包器的效能，因為需要多次應用增量資料才能獲得所需的物件。

--window 的預設值為 10，--depth 的預設值為 50。最大深度為 4095。

--window-memory=<n>

此選項在 --window 之外提供了一個額外限制；視窗大小將動態縮小，以確保佔用的記憶體不超過 <n> 位元組。這對於包含大小混合物件的倉庫很有用，既不會因大視窗而耗盡記憶體，又能充分利用大視窗處理較小物件。大小可以加上“k”、“m”或“g”字尾。--window-memory=0 使記憶體使用無限制。預設值取自 pack.windowMemory 配置變數。

--max-pack-size=<n>

在不尋常的情況下，您可能無法在檔案系統上建立大於特定大小的檔案，此選項可用於告訴命令將輸出的包檔案拆分為多個獨立的包檔案，每個檔案不大於給定大小。大小可以加上“k”、“m”或“g”字尾。允許的最小大小限制為 1 MiB。預設情況下是無限制的，除非設定了配置變數 pack.packSizeLimit。請注意，此選項可能導致倉庫更大且速度更慢；請參閱 pack.packSizeLimit 中的討論。

--honor-pack-keep

此標誌導致已在本地包中且具有 .keep 檔案的物件被忽略，即使它原本會被打包。

--keep-pack=<pack-name>

此標誌導致已在給定包中的物件被忽略，即使它原本會被打包。<pack-name> 是不帶前導目錄的包檔名（例如 pack-123.pack）。該選項可以多次指定以保留多個包。

--incremental

此標誌導致已在包中的物件被忽略，即使它原本會被打包。

--local

此標誌導致從備用物件儲存借用的物件被忽略，即使它原本會被打包。

--non-empty

僅當打包歸檔包含至少一個物件時才建立它。

--progress

預設情況下，當標準錯誤流連線到終端時，會報告進度狀態，除非指定了 -q。此標誌強制報告進度狀態，即使標準錯誤流未定向到終端。

--all-progress

當指定 --stdout 時，進度報告在物件計數和壓縮階段顯示，但在寫入階段被抑制。原因是，在某些情況下，輸出流直接連結到另一個命令，該命令可能希望在處理傳入的包資料時顯示自己的進度狀態。此標誌類似於 --progress，但它強制在寫入階段也顯示進度報告，即使使用了 --stdout。

--all-progress-implied

此選項用於在啟用進度顯示時隱含 --all-progress。與 --all-progress 不同，此標誌本身不會強制顯示任何進度。

-q

此標誌使命令不在標準錯誤流上報告其進度。

--no-reuse-delta

在具有現有包的倉庫中建立打包歸檔時，命令會重用現有增量。這有時會導致包略微次優。此標誌告訴命令不要重用現有增量，而是從頭開始計算它們。

--no-reuse-object

此標誌告訴命令完全不重用現有物件資料，包括未增量化的物件，強制重新壓縮所有內容。這意味著 --no-reuse-delta。僅在需要對打包資料強制執行統一壓縮級別這一不常見的用例中才有用。

--compression=<n>

指定生成的包中新壓縮資料的壓縮級別。如果未指定，包壓縮級別首先由 pack.compression 決定，然後由 core.compression 決定，如果兩者都未設定，則預設為 -1，即 zlib 預設值。如果您想對所有資料強制執行統一壓縮級別，無論來源如何，請新增 --no-reuse-object。

--[no-]sparse

當與“--revs”選項結合使用時，切換“稀疏”演算法以確定要包含在包中的物件。此演算法僅遍歷在引入新物件的路徑中出現的樹。這在計算傳送小更改的包時可以帶來顯著的效能優勢。但是，如果包含的提交包含某些型別的直接重新命名，則可能會向包檔案中新增額外的物件。如果未包含此選項，則預設為 pack.useSparse 的值，該值預設為 true，除非另有指定。

--thin

透過省略傳送方和接收方之間的公共物件來建立“瘦”包，以減少網路傳輸。此選項僅在與 --stdout 結合使用時才有意義。

注意：瘦包透過省略所需物件而違反了打包歸檔格式，因此 Git 無法直接使用它。使用 git index-pack --fix-thin（參見 git-index-pack[1]）來恢復自包含屬性。

--shallow

最佳化將提供給具有淺層倉庫的客戶端的包。此選項與 --thin 結合使用，可以以犧牲速度為代價獲得更小的包。

--delta-base-offset

打包歸檔可以將增量基礎物件表示為 20 位元組的物件名稱或流中的偏移量，但舊版本的 Git 不理解後者。預設情況下，git pack-objects 僅使用前一種格式以獲得更好的相容性。此選項允許命令使用後一種格式以實現緊湊性。根據平均增量鏈長度，此選項通常會將生成的包檔案縮小 3-5%。

注意：像 git gc（參見 git-gc[1]）、git repack（參見 git-repack[1]）這樣的瓷器命令在現代 Git 中將物件放入倉庫的包檔案時，預設會傳遞此選項。當 git bundle（參見 git-bundle[1]）建立捆綁包時也是如此。

--threads=<n>

指定在搜尋最佳增量匹配時要生成的執行緒數。這要求 pack-objects 使用 pthreads 編譯，否則此選項將被忽略併發出警告。這旨在減少多處理器機器上的打包時間。然而，增量搜尋視窗所需的記憶體量將乘以執行緒數。指定 0 將導致 Git 自動檢測 CPU 數量並相應地設定執行緒數。

--index-version=<version>[,<offset>]

此選項僅用於測試套件。它允許強制生成包索引的版本，並強制將位於給定偏移量之上的物件使用 64 位索引條目。

--keep-true-parents

使用此選項，被嫁接（grafts）隱藏的父提交仍將被打包。

--filter=<filter-spec>

從生成的包檔案中省略某些物件（通常是二進位制大物件）。有關有效的 <filter-spec> 形式，請參見 git-rev-list[1]。

--no-filter

關閉任何之前的 --filter= 引數。

--missing=<missing-action>

一個除錯選項，用於幫助未來的“部分克隆”開發。此選項指定如何處理缺失物件。

形式 --missing=error 要求 pack-objects 在遇到缺失物件時停止並報錯。如果倉庫是部分克隆，在宣告物件缺失之前，將嘗試獲取缺失物件。這是預設操作。

形式 --missing=allow-any 將允許在遇到缺失物件時繼續物件遍歷。不會發生缺失物件的獲取。缺失物件將靜默地從結果中省略。

形式 --missing=allow-promisor 類似於 allow-any，但只允許對預期的承諾者（promisor）缺失物件繼續物件遍歷。不會發生缺失物件的獲取。意外的缺失物件將引發錯誤。

--exclude-promisor-objects

省略已知存在於承諾者遠端（promisor remote）中的物件。（此選項的目的是僅對本地建立的物件進行操作，這樣當我們重新打包時，我們仍然可以區分本地建立的物件[不帶 .promisor]和來自承諾者遠端的物件[帶 .promisor]。）這與部分克隆一起使用。

--keep-unreachable

除了不在標有 *.keep 檔案的包中的可達物件外，使用 --unpacked= 選項命名的包中不可達的引用也將新增到生成的包中。這意味著 --revs。

--pack-loose-unreachable

打包不可達的鬆散物件（並刪除其鬆散對應物）。這意味著 --revs。

--unpack-unreachable

以鬆散形式保留不可達物件。這意味著 --revs。

--delta-islands

根據“孤島”限制增量匹配。請參閱下面的 DELTA ISLANDS。

--name-hash-version=<n>

在執行增量壓縮時，Git 會根據啟發式方法（使用物件的路徑）將可能相似的物件分組。雖然按精確路徑匹配進行物件分組對於具有許多版本的路徑很有用，但跨不同完整路徑查詢增量對也有好處。Git 按型別、然後按路徑的“名稱雜湊”、最後按大小收集物件，希望將能夠很好地一起壓縮的物件分組。

預設名稱雜湊版本是 1，它透過將路徑的最後位元組視為對雜湊函式提供最大幅度來優先考慮雜湊區域性性。此版本擅長區分短路徑和查詢跨目錄的重新命名。但是，雜湊函式主要依賴於路徑的最後 16 個位元組。如果倉庫中有很多路徑具有相同的最後 16 個位元組，而僅在父目錄上有所不同，則此名稱雜湊可能導致過多的衝突並導致結果不佳。目前，在使用 --write-bitmap-index 寫入可達性點陣圖檔案時，需要此版本。

名稱雜湊版本 2 具有與版本 1 相似的區域性性特徵，但它單獨考慮每個路徑元件並使用移位疊加雜湊值。這仍然優先考慮路徑的最後位元組，但也使用父目錄名稱對雜湊的低位進行“加鹽”。此方法允許版本 1 的一些區域性性優勢，同時打破了許多不同目錄中出現同名檔案造成的大多數衝突。目前，在使用 --write-bitmap-index 寫入可達性點陣圖檔案時不允許此版本，它將自動更改為版本 1。

增量孤島

在可能的情況下，pack-objects 會嘗試重用現有磁碟上的增量，以避免在執行時搜尋新增量。這對於提供 fetch 服務來說是一項重要的最佳化，因為它意味著伺服器可以完全避免解壓大多數物件，而直接從磁碟傳送位元組。當物件作為增量儲存時，如果接收方沒有其基礎物件（並且我們尚未傳送該基礎物件），則此最佳化將無法奏效。在這種情況下，伺服器會“打破”該增量，並且必須尋找一個新的增量，這會帶來很高的 CPU 開銷。因此，為了效能，磁碟上增量關係中的物件集必須與客戶端將要 fetch 的物件集匹配，這一點非常重要。

在正常的倉庫中，這通常會自動工作。物件大多可以從分支和標籤中訪問，而這正是客戶端 fetch 的內容。我們在伺服器上找到的任何增量都可能在客戶端擁有或將要擁有的物件之間。

但在某些倉庫設定中，您可能擁有幾個相關但獨立的引用指標組，而客戶端傾向於獨立 fetch 這些組。例如，想象您在單個共享物件儲存中託管了倉庫的幾個“分支”，並允許客戶端透過 GIT_NAMESPACE 或使用 alternates 機制將它們視為單獨的倉庫。簡單的 repack 可能會發現某個物件的最佳增量是針對僅在另一個分支中找到的基礎。但是當客戶端 fetch 時，它們將沒有該基礎物件，我們將不得不在執行時尋找新的增量。

如果您有許多在 refs/heads/ 和 refs/tags/ 之外指向相關物件的引用（例如，一些託管服務提供商使用的 refs/pull 或 refs/changes），也可能存在類似情況。預設情況下，客戶端只 fetch 頭和標籤，而針對僅在這些其他組中找到的物件的增量無法按原樣傳送。

增量孤島透過允許您將引用分組為不同的“孤島”來解決此問題。pack-objects 計算哪些物件可以從哪些孤島訪問，並拒絕將物件 A 的增量與不在 A 的所有孤島中的基礎物件關聯。這會導致包略微增大（因為我們錯過了一些增量機會），但保證 fetch 一個孤島時不會因為跨越孤島邊界而需要在執行時重新計算增量。

當使用增量孤島重新打包時，增量視窗往往會因配置禁止的候選物件而堵塞。使用大的 --window 進行重新打包會有所幫助（並且不會像否則那樣花費很長時間，因為我們可以在進行任何內容計算之前根據孤島拒絕某些物件對）。

孤島透過 pack.island 選項配置，該選項可以多次指定。每個值都是匹配引用名稱的左錨定正則表示式。例如

[pack]
island = refs/heads/
island = refs/tags/

將 heads 和 tags 放入一個孤島中（其名稱為空字串；有關命名的更多資訊，請參見下文）。任何不匹配這些正則表示式的引用（例如，refs/pull/123）都不在任何孤島中。因此，任何僅從 refs/pull/ 可達（但不是 heads 或 tags）的物件都不會被用作 refs/heads/ 的基礎。

引用根據其“名稱”分組到孤島中，兩個產生相同名稱的正則表示式被認為屬於同一孤島。名稱是透過連線正則表示式的捕獲組，中間用 - 破折號計算出來的。（如果沒有捕獲組，則名稱為空字串，如上述示例所示。）這允許您建立任意數量的孤島。但是，只支援最多 14 個此類捕獲組。

例如，假設您將每個分支的引用儲存在 refs/virtual/ID 中，其中 ID 是一個數字識別符號。您可能會這樣配置：

[pack]
island = refs/virtual/([0-9]+)/heads/
island = refs/virtual/([0-9]+)/tags/
island = refs/virtual/([0-9]+)/(pull)/

這將把每個分支的 heads 和 tags 放入它們自己的孤島中（命名為“1234”或類似名稱），每個的 pull refs 將進入它們自己的“1234-pull”。

請注意，我們為每個正則表示式選擇一個孤島，採用“後到者勝出”的順序（這允許倉庫特定配置優先於使用者範圍配置，依此類推）。

配置

各種配置變數影響打包，請參見 git-config[1]（搜尋“pack”和“delta”）。

值得注意的是，增量壓縮不用於大於 core.bigFileThreshold 配置變數的物件，也不用於設定了 delta 屬性為 false 的檔案。

另請參閱

git-rev-list[1] git-repack[1] git-prune-packed[1]

GIT

Git[1] 套件的一部分

scroll-to-top