Git
简体中文 ▾ Topics ▾ Latest version ▾ git-cat-file last updated in 2.44.0

名称

git-cat-file - 提供仓库对象的内容或详细信息

概述

git cat-file <类型> <对象>
git cat-file (-e | -p) <对象>
git cat-file (-t | -s) [--allow-unknown-type] <对象>
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]

描述

输出一个或多个对象的内容或其他属性，如大小、类型或 delta 信息。

该命令有两种运行模式，取决于是否指定了 --batch 系列选项。

在非批处理模式下，该命令提供命令行中命名的对象的信息。

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

选项

<对象>

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

-t

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

-s

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

-e

如果 <对象> 存在且是有效对象，则以零状态退出。如果 <对象> 的格式无效，则以非零状态退出，并在标准错误流上显示错误信息。

-p

根据 <对象> 的类型漂亮地打印其内容。

<类型>

通常情况下，这与 <对象> 的真实类型相匹配，但也允许要求一个可以从给定的 <对象> 中简单地反向引用的类型。 例如，要求输入 “目录树”，而 <对象> 是包含它的提交对象，或者要求输入 "blob"，而 <对象> 是指向它的标记对象。

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

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

--textconv

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

--filters

显示经当前工作树中为给定的 <路径> 配置的过滤器（即污点过滤器、行结束符转换等）转换后的内容。在这种情况下，<对象> 的形式必须是`<目录树对象>:<路径>，或 `:<路径>。

--path=<路径>

与 `--textconv`或 `--filters`一起使用，允许分别指定对象名称和路径，例如，当难以确定 blob 来自哪个版本时。

--batch
--batch=<格式>

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

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

  • 与 --use-mailmap 一起使用时，对于提交和标记对象，输出的内容部分显示使用邮件映射机制替换的身份，而输出的信息部分显示对象的大小，就像实际记录了替换的身份一样。

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

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

  • 与 --textconv 或 --filters 一起使用时，输入行必须 指定路径，以空格分隔。 详见下文 批输出 部分。

  • 与 --use-mailmap 一起使用时，对于提交和标记对象，打印的对象信息会显示该对象的大小，就好像其中记录的身份信息被邮件映射机制替换了一样。

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

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

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

  • 当与 --use-mailmap`一起使用时，对于提交和标记对象，`contents 命令会显示使用邮件映射机制替换的标识，而 info 命令则会显示对象的大小，就像实际记录了替换的标识一样。

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

contents <对象>

打印对象引用 <对象> 的对象内容。这相当于 --batch 的输出。

info <对象>

打印对象引用 <对象> 的对象信息。这相当于 --batch-check 的输出。

flush （刷新）

与 --buffer 一起使用时，执行自开始或上次刷新后发出的所有命令。使用 --buffer 时，在发出 flush 之前不会有输出。不使用 --buffer 时，每次刷新命令时都不会发出 flush。

--batch-all-objects

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

--buffer

通常情况下，批处理输出会在每个对象输出后刷新，以便进程可以交互式地从 cat-file 读写。使用此选项后，输出将使用正常的标准 IO 缓冲；在对大量对象调用 --batch-check 或 --batch-command 时，这种方式效率更高。

--unordered

当使用 --batch-all-objects 时，访问对象的顺序可能比散列顺序更有效率。顺序的具体细节未作规定，但如果不需要特定顺序，通常会加快输出速度，特别是在使用 --batch`时。 请注意，即使每个对象在仓库中存储了多次，`cat-file 仍然只会显示一次。

--allow-unknown-type

允许 -s 或 -t 查询已损坏/损坏的未知类型对象。

--follow-symlinks

使用 --batch 或 --batch-check 选项，在请求使用 tree-ish:path-in-tree 形式的扩展 SHA-1 表达式的对象时，可跟踪仓库内部的符号链接。 与其提供链接本身的输出，不如提供链接对象的输出。 如果符号链接指向 tree-ish 以外（例如指向 /foo 的链接或指向 ../foo 的根级链接），则会打印链接在目录树外的部分。

如果指定的是索引中的对象（例如，:link 而不是 HEAD:link）而不是树中的对象，该选项（目前）无法正常工作。

除非使用了 --batch 或 --batch-check 选项，否则（目前）不能使用该选项。

例如，考虑一个包含以下内容的 git 仓库：

f: 包含 "hello\n" 的文件
link: 链接到 f 的符号链接
dir/link: 链接到 ../f 的符号连接
plink: 链接到 ../f 的符号连接
alink: 链接到 /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`相同的方式打印内容。

您可以使用自定义的 <format>，指定每个对象显示的信息。每个对象的 <format> 都会按字面意思复制到标准输出流，并以 `%(atom)`形式展开占位符，然后换行。可用的原子项有：

objectname

对象名称的十六进制全称。

objecttype

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

objectsize

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

objectsize:disk

对象在磁盘上占用的大小（以字节为单位）。请参阅下文 注意事项 部分关于磁盘大小的说明。

deltabase

如果对象以 delta 格式存储在磁盘上，则扩展为 delta 基本对象名称的十六进制表示法。 否则，将扩展为空 OID（全部为零）。请参阅下面的 注意事项。

rest

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

如果未指定格式，默认格式为 %（对象名）%（对象类型）%（对象大小）。

如果指定了 --batch，或者 --batch-command`与 `内容 命令一起使用，则对象信息之后是对象内容（由 %(objectize) 字节组成），之后是换行符。

例如，不使用自定义格式的 --batch 会产生结果：

<对象 ID> SP <类型> SP <尺寸> LF
<内容> LF

而 --batch-check='%(objectname) %(objecttype)' 则会产生：

<对象 ID> SP <类型> LF

如果在标准输入流中指定的名称无法解析为版本库中的对象，那么 cat-file 将忽略任何自定义格式并打印：

<对象> SP 丢失 LF

如果指定的名称可能指向多个对象（模棱两可的 短 sha），则 cat-file 将忽略任何自定义格式并打印：

<对象> SP ambiguous LF

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

符号链接 SP <size> LF
<符号链接> LF

符号链接要么是绝对的（以 / 开头），要么是相对于树根的。 例如，如果 dir/link 指向 .././foo，那么 <符号链接> 将是 ../foo。 <尺寸> 是符号链接的大小（以字节为单位）。

如果使用 --follow-symlinks，将显示以下错误信息：

<对象> SP 丢失 LF

会在请求的初始符号链接不存在时打印出来。

dangling SP <尺寸> LF
<对象> LF

会在初始符号链接存在，但它（transitive-of）指向的东西不存在时打印出来。

loop SP <尺寸> LF
<对象> LF

会打印符号链接循环（或任何需要超过 40 个链接分辨率才能解析的符号链接）。

notdir SP <尺寸> LF
<对象> LF

会被打印出来，因为在符号链接解析过程中，文件被用作目录名。

或者，当传递 -Z 时，上述任何示例中的换行符都会被 NUL 结束符取代。这样可以确保在输出本身包含换行符的情况下，输出仍可解析，因此推荐用于脚本目的。

注意事项

需要注意的是，磁盘上对象的大小会被准确地报告出来，但在得出哪些记录或对象造成了磁盘使用量的结论时应小心谨慎。打包的非 delta 对象的大小可能远大于与之相对的 delta 对象的大小，但选择哪个对象为基准对象，哪个对象为 delta 对象是任意的，在重新打包时可能会发生变化。

还请注意，对象数据库中可能存在一个对象的多个副本；在这种情况下，无法确定将报告哪个副本的大小或 delta 基数。

GIT

属于 git[1] 文档

scroll-to-top