簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-cat-file 最後更新於 2.52.0

名稱

git-cat-file - 提供倉庫物件的內容或詳細資訊

概要

git cat-file <type> <object>
git cat-file (-e | -p | -t | -s) <object>
git cat-file (--textconv | --filters)
	     [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
	     [--buffer] [--follow-symlinks] [--unordered]
	     [--textconv | --filters] [-Z]

描述

輸出一個或多個物件的內容或其他屬性，如大小、型別或增量資訊。

此命令可以根據是否指定了 --batch 系列選項，在兩種模式下執行。

在非批次模式下，命令提供命令列上命名的物件的資訊。

在批次模式下，引數從標準輸入讀取。

選項

<object>

要顯示的物件的名稱。有關拼寫物件名稱的更完整的列表，請參閱 gitrevisions[7] 中的“指定修訂版本”部分。

-t

不顯示內容，而是顯示由 <object> 標識的物件型別。

-s

不顯示內容，而是顯示由 <object> 標識的物件大小。如果與 --use-mailmap 選項一起使用，將顯示在透過 mailmap 機制替換識別符號後更新物件的大小。

-e

如果 <object> 存在且是有效物件，則以零狀態退出。如果 <object> 格式無效，則以非零狀態退出並在 stderr 上發出錯誤。

-p

根據 <object> 的型別，以漂亮的格式列印其內容。

<type>

通常，這與 <object> 的實際型別匹配，但也可以要求一個可以從給定的 <object> 中簡單解引用的型別。例如，可以要求一個“tree”，其中 <object> 是包含它的提交物件；或者要求一個“blob”，其中 <object> 是指向它的標籤物件。

--mailmap
--no-mailmap
--use-mailmap
--no-use-mailmap

使用 mailmap 檔案將作者、提交者和標記者的姓名和電子郵件地址對映到規範的真實姓名和電子郵件地址。請參閱 git-shortlog[1]。

--textconv

以文字轉換過濾器處理後的內容顯示。在這種情況下，<object> 必須是 <tree-ish>:<path> 或 :<path> 的形式，才能將過濾器應用於在索引中記錄的 <path> 的內容。

--filters

以當前工作樹中為給定 <path> 配置的過濾器（例如，smudge 過濾器、換行符轉換等）轉換後的內容顯示。在這種情況下，<object> 必須是 <tree-ish>:<path> 或 :<path> 的形式。

--filter=<filter-spec>
--no-filter

從要列印的物件列表中排除物件。這隻能與批次模式之一結合使用。透過任何透過標準輸入讀取物件的批次模式（--batch、--batch-check）顯式請求的已排除物件將被報告為“filtered”。在 --batch-all-objects 模式下的已排除物件將根本不會被列印。<filter-spec> 可以是以下之一：

--filter=blob:none 的形式將排除所有 blob。

--filter=blob:limit=<n>[kmg] 的形式將排除大小至少為 n 位元組或單位的 blob。n 可以為零。字尾 k、m 和 g 可用於命名 KiB、MiB 或 GiB 的單位。例如，blob:limit=1k 與 blob:limit=1024 相同。

--filter=object:type=(tag|commit|tree|blob) 的形式將排除所有非請求型別的物件。

--path=<path>

與 --textconv 或 --filters 一起使用，允許單獨指定物件名稱和路徑，例如，當難以確定 blob 來自哪個修訂版本時。

--batch
--batch=<format>

為 stdin 提供的每個物件列印物件資訊和內容。不能與除 --textconv、--filters 或 --use-mailmap 之外的任何其他選項或引數組合。

  • 與 --textconv 或 --filters 一起使用時，輸入行必須指定路徑，並用空格分隔。有關詳細資訊，請參閱下面的 批次輸出 部分。

  • 與 --use-mailmap 一起使用時，對於提交物件和標籤物件，輸出的內容部分顯示透過 mailmap 機制替換的識別符號，而輸出的資訊部分顯示物件的大小，就好像它實際記錄了替換的識別符號一樣。

--batch-check
--batch-check=<format>

列印 stdin 提供的每個物件的資訊。不能與除 --textconv、--filters 或 --use-mailmap 之外的任何其他選項或引數組合。

  • 與 --textconv 或 --filters 一起使用時，輸入行必須指定路徑，並用空格分隔。有關詳細資訊，請參閱下面的 批次輸出 部分。

  • 與 --use-mailmap 一起使用時，對於提交物件和標籤物件，列印的物件資訊顯示物件的大小，就好像其中記錄的識別符號已被 mailmap 機制替換一樣。

--batch-command
--batch-command=<format>

進入一個從 stdin 讀取命令和引數的命令模式。只能與 --buffer、--textconv、--use-mailmap 或 --filters 組合使用。

  • 與 --textconv 或 --filters 一起使用時，輸入行必須指定路徑，並用空格分隔。有關詳細資訊，請參閱下面的 批次輸出 部分。

  • 與 --use-mailmap 一起使用時，對於提交物件和標籤物件，contents 命令顯示透過 mailmap 機制替換的識別符號，而 info 命令顯示物件的大小，就好像它實際記錄了替換的識別符號一樣。

--batch-command 識別以下命令：

contents <object>

列印物件引用 <object> 的物件內容。這對應於 --batch 的輸出。

info <object>

列印物件引用 <object> 的物件資訊。這對應於 --batch-check 的輸出。

flush

與 --buffer 一起使用，以執行自開始或自上一個 flush 以來的所有先前發出的命令。當使用 --buffer 時，在發出 flush 之前不會有任何輸出。當不使用 --buffer 時，命令會在每次發出時重新整理，而無需發出 flush。

--batch-all-objects

不是讀取 stdin 上的物件列表，而是對倉庫中的所有物件以及任何備用物件儲存（不僅僅是可達物件）執行請求的批次操作。需要指定 --batch 或 --batch-check。預設情況下，物件按其雜湊值排序訪問；另請參閱下面的 --unordered。物件按原樣呈現，不遵循 git-replace[1] 的“replace”機制。

--buffer

通常，批次輸出在每個物件輸出後重新整理，以便程序可以互動地讀寫 cat-file。使用此選項時，輸出使用正常的 stdio 緩衝；當對大量物件呼叫 --batch-check 或 --batch-command 時，這會更有效。

--unordered

當使用 --batch-all-objects 時，按照可能比雜湊順序更有效地訪問物件內容的順序來訪問物件。順序的具體細節未指定，但如果您不需要特定順序，這通常會產生更快的輸出，尤其是在使用 --batch 時。請注意，cat-file 仍會顯示每個物件一次，即使它在倉庫中儲存了多次。

--follow-symlinks

與 --batch 或 --batch-check 一起使用時，在請求形式為 tree-ish:path-in-tree 的擴充套件 SHA-1 表示式的物件時，會跟隨倉庫內的符號連結。而不是提供關於連結本身的輸出，而是提供關於連結指向的物件的資訊。如果符號連結指向樹之外（例如，連結到 /foo 或指向 ../foo 的根級別連結），將列印連結中樹之外的部分。

此選項（目前）當指定索引中的物件（例如 :link 而不是 HEAD:link）而不是樹中的物件時，不起作用。

此選項（目前）除非使用 --batch 或 --batch-check，否則無法使用。

例如，考慮一個 git 倉庫，其中包含

f: a file containing "hello\n"
link: a symlink to f
dir/link: a symlink to ../f
plink: a symlink to ../f
alink: a symlink to /etc/passwd

對於常規檔案 f，echo HEAD:f | git cat-file --batch 將列印：

ce013625030ba8dba906f756967f9e9ca394464a blob 6

而 echo HEAD:link | git cat-file --batch --follow-symlinks 將列印相同的內容，HEAD:dir/link 也是如此，因為它們都指向 HEAD:f。

不使用 --follow-symlinks 時，這些命令將列印關於符號連結本身的資料。對於 HEAD:link，您將看到：

4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1

plink 和 alink 都指向樹之外，因此它們將分別列印：

symlink 4
../f
symlink 11
/etc/passwd
-Z

僅對 --batch、--batch-check 或 --batch-command 有意義；輸入和輸出是 NUL 分隔的，而不是換行符分隔的。

-z

僅對 --batch、--batch-check 或 --batch-command 有意義；輸入是 NUL 分隔的，而不是換行符分隔的。此選項已棄用，改為使用 -Z，因為否則輸出可能不明確。

輸出

如果指定了 -t，則會輸出 <type> 之一。

如果指定了 -s，則會輸出 <object> 的大小（以位元組為單位）。

如果指定了 -e，則不輸出，除非 <object> 格式錯誤。

如果指定了 -p，則會以漂亮的格式列印 <object> 的內容。

如果指定了 <type>，則會返回 <object> 的原始（但未壓縮）內容。

批次輸出

如果給出了 --batch 或 --batch-check，cat-file 將從 stdin 讀取物件，每行一個，並按讀取的順序列印有關它們的資訊。預設情況下，整行被視為一個物件，就好像它被饋送到 git-rev-parse[1] 一樣。

當給出 --batch-command 時，cat-file 將從 stdin 讀取命令，每行一個，並根據給定的命令列印資訊。使用 --batch-command 時，info 命令後跟一個物件將列印關於該物件的資訊，方式與 --batch-check 類似；contents 命令後跟一個物件將以與 --batch 類似的方式列印內容。

您可以透過使用自定義 <format> 來指定要顯示的每個物件的資訊。<format> 按字面複製到 stdout，並對佔位符 %(atom) 進行展開，然後是一個換行符。可用的 atom 是：

objectname

物件的完整十六進位制表示。

objecttype

物件的型別（與 cat-file -t 報告的相同）。

objectmode

如果指定的物件具有模式資訊（例如，樹或索引條目），則以八進位制整數形式表示的模式。否則，為空字串。

objectsize

物件的大小（以位元組為單位，與 cat-file -s 報告的大小相同）。

objectsize:disk

物件在磁碟上佔用的位元組數。有關磁碟上大小的說明，請參閱下面的 注意事項 部分。

deltabase

如果物件在磁碟上儲存為增量，則此項擴充套件為增量基礎物件名稱的完整十六進位制表示。否則，擴充套件為 null OID（全零）。請參閱下面的 注意事項。

rest

如果此 atom 出現在輸出字串中，輸入行將在第一個空格邊界處拆分。該空格之前的所有字元被視為物件名稱；該空格之後的字元（即行的“rest”）將替換 %(rest) atom 輸出。

如果未指定格式，則預設格式為 %(objectname) %(objecttype) %(objectsize)。

如果指定了 --batch，或者如果 --batch-command 與 contents 命令一起使用，則物件資訊之後是物件內容（包含 %(objectsize) 位元組），然後是一個換行符。

例如，沒有自定義格式的 --batch 將產生：

<oid> SP <type> SP <size> LF
<contents> LF

而 --batch-check='%(objectname) %(objecttype) 將產生：

<oid> SP <type> LF

如果在 stdin 上指定的名稱無法解析為倉庫中的物件，則 cat-file 將忽略任何自定義格式並列印：

<object> SP missing LF

如果 stdin 上指定的名稱被 --filter= 過濾掉，則 cat-file 將忽略任何自定義格式並列印：

<object> SP excluded LF

如果指定了可能指向多個物件的名稱（歧義的短 sha），則 cat-file 將忽略任何自定義格式並列印：

<object> SP ambiguous LF

如果指定的名稱指向樹中的子模組條目，並且目標物件在倉庫中不存在，則 cat-file 將忽略任何自定義格式並列印（帶有子模組的物件 ID）：

<oid> SP submodule LF

如果使用了 --follow-symlinks，並且倉庫中的符號連結指向倉庫之外，則 cat-file 將忽略任何自定義格式並列印：

symlink SP <size> LF
<symlink> LF

符號連結將是絕對的（以 / 開頭），或者相對於樹的根目錄。例如，如果 dir/link 指向 ../../foo，則 <symlink> 將是 ../foo。<size> 是符號連結的大小（以位元組為單位）。

如果使用了 --follow-symlinks，將顯示以下錯誤訊息：

<object> SP missing LF

在請求的初始符號連結不存在時列印。

dangling SP <size> LF
<object> LF

當初始符號連結存在，但它（傳遞地）指向的某個物件不存在時列印。

loop SP <size> LF
<object> LF

對於符號連結迴圈（或任何需要超過 40 次連結解析才能解析的符號連結）列印。

notdir SP <size> LF
<object> LF

在符號連結解析過程中，將檔名用作目錄名時列印。

或者，當傳遞 -Z 時，上面任何示例中的換行符都將被 NUL 終止符替換。這確保瞭如果輸出本身包含換行符，輸出仍然是可解析的，因此建議用於指令碼用途。

注意事項

請注意，物件在磁碟上的大小報告準確，但應謹慎推斷哪些引用或物件導致磁碟使用。打包的非增量物件的大小可能遠大於對其進行增量的物件的大小，但基礎物件和增量物件的選擇是任意的，並且在重新打包期間可能會發生變化。

另請注意，物件資料庫中可能存在同一物件的多個副本；在這種情況下，報告哪個副本的大小或增量基礎是未定義的。

GIT

Git[1] 套件的一部分