簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-ls-tree 最後更新於 2.42.0

名稱

git-ls-tree - 列出 tree 物件的內容

概要

git ls-tree [-d] [-r] [-t] [-l] [-z]
	    [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>]
	    <tree-ish> [<path>…​]

描述

列出給定 tree 物件的內容，類似於當前工作目錄中的 "/bin/ls -a" 命令。請注意，

  • 其行為與 "/bin/ls" 略有不同，因為 <path> 僅表示要匹配的模式列表，例如，指定目錄名（不帶 -r）的行為會有所不同，並且引數的順序無關緊要。

  • 其行為與 "/bin/ls" 類似，因為 <path> 是相對於當前工作目錄的。例如，當您在目錄 sub 中，該目錄包含目錄 dir，您可以執行 git ls-tree -r HEAD dir 來列出 tree 的內容（在 HEAD 中為 sub/dir）。在這種情況下，您不希望提供一個不在根級別的 tree（例如 git ls-tree -r HEAD:sub dir），因為這會導致在 HEAD 提交中請求 sub/sub/dir。但是，可以透過傳遞 --full-tree 選項來忽略當前工作目錄。

選項

<tree-ish>

tree-ish 的 ID。

-d

僅顯示指定的 tree 條目本身，而不顯示其子項。

-r

遞迴進入子 tree。

-t

即使在遞迴子 tree 時也顯示 tree 條目。如果未傳遞 -r，則此選項無效。-d 暗示 -t。

-l
--long

顯示 blob（檔案）條目的物件大小。

-z

輸出時使用 \0 行終止符，並且不對檔名進行引用。有關更多資訊，請參見下面的輸出格式。

--name-only
--name-status

僅列出檔名（而不是 "long" 輸出），每行一個。不能與 --object-only 結合使用。

--object-only

僅列出物件名稱，每行一個。不能與 --name-only 或 --name-status 結合使用。這等同於指定 --format='%(objectname)，但對於此選項和該精確格式，命令採用經過手工最佳化的程式碼路徑，而不是透過通用格式化機制。

--abbrev[=<n>]

而不是顯示完整的 40 位元組十六進位制物件行，顯示至少 <n> 個十六進位制數字長且能唯一引用該物件的最小字首。可以透過 --abbrev=<n> 指定非預設數字。

--full-name

而不是顯示相對於當前工作目錄的路徑名，而是顯示完整的路徑名。

--full-tree

不將列表限制在當前工作目錄。暗含 --full-name。

--format=<format>

一個字串，用於插值正在顯示的 %(fieldname) 欄位。它還將 %% 插值為 %，以及 %xNN（其中 NN 是十六進位制數字）插值為十六進位制程式碼為 NN 的字元；例如，%x00 插值為 \0 (NUL)，%x09 插值為 \t (TAB)，%x0a 插值為 \n (LF)。指定時，--format 不能與其他改變格式的選項結合使用，包括 --long、--name-only 和 --object-only。

[<path>…​]

當指定路徑時，顯示它們（請注意，這並非真正意義上的原始路徑名，而是要匹配的模式列表）。否則，隱式地使用 tree 的根級別作為唯一的路徑引數。

輸出格式

ls-tree 的輸出格式由 --format 選項或其他改變格式的選項（如 --name-only 等）決定（參見上面的 --format）。

使用某些 --format 指令等同於使用這些選項，但呼叫完整的格式化機制可能比使用適當的格式化選項慢。

在 --format 與現有選項完全匹配的情況下，ls-tree 將使用相應的更快的路徑。因此，預設格式等同於

%(objectmode) %(objecttype) %(objectname)%x09%(path)

此輸出格式與 git update-index 的 --index-info --stdin 所期望的格式相容。

當使用 -l 選項時，格式變為

%(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)

由 <objectname> 標識的物件大小以位元組為單位給出，並右對齊，最小寬度為 7 個字元。僅為 blob（檔案）條目給出物件大小；對於其他條目，則用 - 字元代替大小。

如果不使用 -z 選項，則具有“特殊”字元的路徑名將像 core.quotePath 配置變數（參見 git-config[1]）中解釋的那樣被引用。使用 -z 時，檔名將按原樣輸出，行以 NUL 位元組結束。

自定義格式

可以透過使用 --format 選項以自定義格式列印，該選項能夠使用 %(fieldname) 表示法插值不同的欄位。例如，如果您只關心 "objectname" 和 "path" 欄位，您可以執行具有特定 "--format" 的命令，如下所示：

git ls-tree --format='%(objectname) %(path)' <tree-ish>

欄位名稱

結構化欄位的各種值可用於插值到結果輸出中。對於每個輸出行，可以使用以下名稱：

objectmode

物件的模式。

objecttype

物件的型別（commit、blob 或 tree）。

objectname

物件的名稱。

objectsize[:padded]

blob 物件的大小（如果是 commit 或 tree，則為 "-"）。它還支援使用 "%(objectsize:padded)" 的填充格式。

path

物件的路徑名。

GIT

Git[1] 套件的一部分