简体中文 ▾ 主题 ▾ 最新版本 ▾ 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] 套件的一部分