简体中文 ▾ 主题 ▾ 最新版本 ▾ git-cat-file 上次更新于 2.50.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 系列中的选项。

在非批量模式下，此命令提供命令行上指定对象的详细信息。

在批量模式下，参数从标准输入读取。

选项

<对象>

要显示的对象名称。有关拼写对象名称的更完整列表，请参阅 gitrevisions[7] 中的“指定修订版本”部分。

-t

不显示内容，而是显示由 <对象> 标识的对象类型。

-s

不显示内容，而是显示由 <对象> 标识的对象大小。如果与 --use-mailmap 选项一起使用，将在使用 mailmap 机制替换标识后显示更新对象的大小。

-e

如果 <对象> 存在且是有效对象，则以零状态退出。如果 <对象> 格式无效，则以非零状态退出并在标准错误输出错误。

-p

根据 <对象> 的类型美化打印其内容。

<类型>

通常这与 <对象> 的实际类型匹配，但也允许请求可以从给定 <对象> 轻松解引用的类型。例如，请求一个“tree”（树）类型，而 <对象> 是包含它的提交对象；或者请求一个“blob”（二进制大对象）类型，而 <对象> 是指向它的标签对象。

--[no-]mailmap
--[no-]use-mailmap

使用 mailmap 文件将作者、提交者和标记者的姓名和电子邮件地址映射到规范的真实姓名和电子邮件地址。参阅 git-shortlog[1]。

--textconv

显示经 textconv 过滤器转换后的内容。在这种情况下，<对象> 必须是 <tree-ish>:<路径> 或 :<路径> 的形式，以便将过滤器应用于索引中 <路径> 处记录的内容。

--filters

显示经当前工作树中为给定 <路径> 配置的过滤器（即 smudge 过滤器、行尾转换等）转换后的内容。在这种情况下，<对象> 必须是 <tree-ish>:<路径> 或 :<路径> 的形式。

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

从打印对象列表中省略对象。此选项只能与批量模式之一结合使用。通过任何从标准输入读取对象的批量模式（--batch、--batch-check）明确请求的排除对象将被报告为“已过滤”。在 --batch-all-objects 模式下，排除对象将完全不打印。<filter-spec> 可以是以下之一：

形式 --filter=blob:none 将省略所有二进制大对象（blob）。

形式 --filter=blob:limit=<n>[kmg] 将省略大小至少为 n 字节或单位的二进制大对象。n 可以为零。后缀 k、m 和 g 可用于表示 KiB、MiB 或 GiB 中的单位。例如，blob:limit=1k 与 blob:limit=1024 相同。

形式 --filter=object:type=(tag|commit|tree|blob) 将省略所有不属于请求类型的对象。

--path=<路径>

与 --textconv 或 --filters 一起使用，允许单独指定对象名称和路径，例如当难以找出二进制大对象（blob）来源的修订版本时。

--batch
--batch=<格式>

为标准输入中提供的每个对象打印对象信息和内容。不得与除 --textconv、--filters 或 --use-mailmap 之外的任何其他选项或参数组合使用。

  • 与 --textconv 或 --filters 一起使用时，输入行必须指定路径，用空格分隔。有关详细信息，请参阅下面的 批量 输出 部分。

  • 与 --use-mailmap 一起使用时，对于提交（commit）和标签（tag）对象，输出的内容部分显示使用 mailmap 机制替换后的标识，而输出的信息部分显示对象的大小，就好像它实际记录了替换后的标识一样。

--batch-check
--batch-check=<格式>

为标准输入中提供的每个对象打印对象信息。不得与除 --textconv、--filters 或 --use-mailmap 之外的任何其他选项或参数组合使用。

  • 与 --textconv 或 --filters 一起使用时，输入行必须指定路径，用空格分隔。有关详细信息，请参阅下面的 批量 输出 部分。

  • 与 --use-mailmap 一起使用时，对于提交（commit）和标签（tag）对象，打印的对象信息显示对象的大小，就好像其中记录的标识已通过 mailmap 机制替换一样。

--batch-command
--batch-command=<格式>

进入命令模式，从标准输入读取命令和参数。只能与 --buffer、--textconv、--use-mailmap 或 --filters 组合使用。

  • 与 --textconv 或 --filters 一起使用时，输入行必须指定路径，用空格分隔。有关详细信息，请参阅下面的 批量 输出 部分。

  • 与 --use-mailmap 一起使用时，对于提交（commit）和标签（tag）对象，contents 命令显示使用 mailmap 机制替换后的标识，而 info 命令显示对象的大小，就好像它实际记录了替换后的标识一样。

--batch-command 识别以下命令：

contents <对象>

为对象引用 <对象> 打印对象内容。这与 --batch 的输出相对应。

info <对象>

为对象引用 <对象> 打印对象信息。这与 --batch-check 的输出相对应。

flush

与 --buffer 一起使用，以执行自开始或上次发出 flush 命令以来发出的所有先前命令。当使用 --buffer 时，在发出 flush 命令之前不会有任何输出。当不使用 --buffer 时，命令每次都会刷新，而无需发出 flush 命令。

--batch-all-objects

不从标准输入读取对象列表，而是对仓库中所有对象和任何备用对象存储（不仅仅是可到达的对象）执行请求的批量操作。需要指定 --batch 或 --batch-check。默认情况下，对象按其哈希排序访问；另请参阅下面的 --unordered。对象按原样呈现，不遵循 git-replace[1] 的“替换”机制。

--buffer

通常，批量输出在每个对象输出后立即刷新，以便进程可以与 cat-file 进行交互式读写。使用此选项，输出使用正常的标准 I/O 缓冲；这在对大量对象调用 --batch-check 或 --batch-command 时效率更高。

--unordered

当使用 --batch-all-objects 时，以一种可能比哈希顺序更有效的方式访问对象内容的顺序来访问对象。确切的顺序细节未指定，但如果您不需要特定顺序，这通常会产生更快的输出，尤其是在使用 --batch 时。请注意，即使对象在仓库中存储多次，cat-file 仍只会显示每个对象一次。

--follow-symlinks

使用 --batch 或 --batch-check 时，当请求形式为 tree-ish:path-in-tree 的扩展 SHA-1 表达式对象时，遵循仓库内部的符号链接。不提供关于链接本身的输出，而是提供关于链接到对象的输出。如果符号链接指向 tree-ish 外部（例如，指向 /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，则为 <类型> 之一。

如果指定了 -s，则为 <对象> 的大小（以字节为单位）。

如果指定了 -e，则无输出，除非 <对象> 格式错误。

如果指定了 -p，则 <对象> 的内容将美化打印。

如果指定了 <类型>，将返回 <对象> 的原始（尽管未压缩）内容。

批量输出

如果给定 --batch 或 --batch-check，cat-file 将从标准输入逐行读取对象，并以读取它们的相同顺序打印有关它们的信息。默认情况下，整行被视为一个对象，就好像它被馈送到 git-rev-parse[1] 一样。

当给定 --batch-command 时，cat-file 将从标准输入逐行读取命令，并根据给定命令打印信息。使用 --batch-command，info 命令后跟一个对象将以与 --batch-check 相同的方式打印有关对象的信息，而 contents 命令后跟一个对象将以与 --batch 相同的方式打印内容。

您可以通过使用自定义 <格式> 指定为每个对象显示的信息。 <格式> 将按字面复制到每个对象的标准输出，其中 %(atom) 形式的占位符将被展开，后跟一个换行符。可用的原子有：

objectname

对象名称的完整十六进制表示。

objecttype

对象的类型（与 cat-file -t 报告的相同）。

objectsize

对象的大小（以字节为单位，与 cat-file -s 报告的相同）。

objectsize:disk

对象在磁盘上占用的字节大小。请参阅下面 注意事项 部分中关于磁盘大小的说明。

deltabase

如果对象在磁盘上以增量（delta）形式存储，则此项展开为增量基础对象名称的完整十六进制表示。否则，展开为空 OID（全零）。请参阅下面的 注意事项。

rest

如果在输出字符串中使用此原子，则输入行将在第一个空白边界处拆分。该空白之前的所有字符都被视为对象名称；该第一个空白运行之后的字符（即行的“其余部分”）将输出以代替 %(rest) 原子。

如果未指定格式，则默认格式为 %(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

如果在标准输入上指定了无法解析为仓库中对象的名称，则 cat-file 将忽略任何自定义格式并打印

<object> SP missing LF

如果在标准输入上指定了通过 --filter= 过滤掉的名称，则 cat-file 将忽略任何自定义格式并打印

<object> SP excluded LF

如果指定的名称可能引用多个对象（模糊的短 SHA），则 cat-file 将忽略任何自定义格式并打印

<object> SP ambiguous LF

如果使用 --follow-symlinks，并且仓库中的符号链接指向仓库外部，则 cat-file 将忽略任何自定义格式并打印

symlink SP <size> LF
<symlink> LF

符号链接可以是绝对路径（以 / 开头），也可以是相对于树根的路径。例如，如果 dir/link 指向 ../../foo，则 <符号链接> 将是 ../foo。 <大小> 是符号链接的大小（以字节为单位）。

如果使用 --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 终止符。这确保了如果输出本身包含换行符，输出仍然可解析，因此建议用于脚本目的。

注意事项

请注意，磁盘上对象的大小报告是准确的，但在得出关于哪些引用或对象导致磁盘占用的结论时应谨慎。打包的非增量（non-delta）对象的大小可能远大于对其进行增量（delta）的对象的大小，但选择哪个对象作为基础和哪个作为增量是任意的，并且在重新打包（repack）期间可能会更改。

另请注意，对象数据库中可能存在对象的多个副本；在这种情况下，报告哪个副本的大小或增量（delta）基础是未定义的。

GIT

Git[1] 套件的一部分

scroll-to-top