English ▾ 主題 ▾ 最新版本 ▾ git-ls-tree 最後更新於 2.42.0

名稱

git-ls-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>…​]

描述

列出給定樹狀物件的內容，如同在當前工作目錄下執行 "/bin/ls -a" 一樣。請注意，

  • 其行為與 "/bin/ls" 略有不同，因為 <path> 僅代表要比對的模式列表，例如指定目錄名稱（未加 -r 時）會有不同的行為，且參數的順序並不重要。

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

選項

<tree-ish>

樹狀表示式 (tree-ish) 的 ID。

-d

僅顯示已命名的樹狀條目本身，不顯示其子項。

-r

遞迴進入子樹。

-t

即使在遞迴時也顯示樹狀條目。如果未傳遞 -r，則無效。-d 隱含 -t。

-l
--long

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

-z

輸出時以 \0 作為行結尾，且不對檔案名稱加引號。詳細資訊請參閱下方的「輸出格式」。

--name-only
--name-status

僅列出檔案名稱（而非「長格式」輸出），每行一個。不能與 --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>…​]

當給定路徑時，顯示它們（請注意，這並非真正的原始路徑名稱，而是一組要比對的模式列表）。否則，預設隱含使用樹的根層級作為唯一的路徑參數。

輸出格式

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

物件的模式 (mode)。

objecttype

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

objectname

物件的名稱。

objectsize[:padded]

blob 物件的大小（如果是 commit 或 tree 則顯示 "-"）。它也支援 "%(objectsize:padded)" 的填充大小格式。

path

物件的路徑名稱。

GIT

git[1] 套件的一部分