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