git-cat-file

命令名称 - 提供仓库对象的内容或详细信息

概要

bash

[verse]
'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 - 显示经过 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 表达式请求对象时，跟踪仓库内的符号链接。不是提供关于链接本身的输出，而是提供关于链接目标对象的输出。如果符号链接指向 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，则输出 <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 - 如果对象以增量形式存储在磁盘上，这将展开为增量基础对象名称的完整十六进制表示。否则展开为空 OID（全零）。请参阅下面的"注意事项"。
rest - 如果此 atom 在输出字符串中使用，输入行将在第一个空白边界处拆分。该空白之前的所有字符被视为对象名称；第一个空白之后的字符（即行的"其余"部分）在 %(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。
对于符号链接循环（或需要超过 40 次链接解析才能解析的符号链接），打印 loop SP <size> LF <object> LF。
当在符号链接解析过程中，文件被用作目录名时，打印 notdir SP <size> LF <object> LF。

另外，当传递 -Z 时，上述所有示例中的换行符被替换为 NUL 终止符。这确保了输出本身包含换行符时输出仍可解析，因此建议用于脚本目的。

注意事项

请注意，磁盘上对象的大小报告是准确的，但在得出哪些引用或对象对磁盘使用负责的结论时应小心。打包的非增量对象的大小可能比对其进行增量的对象的大小大得多，但选择哪个对象作为基础、哪个作为增量是任意的，并且在重新打包期间可能会发生变化。

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

Git

git(1) 套件的一部分

git-cat-file ​

概要 ​

描述 ​

选项 ​

输出 ​

批量输出 ​

注意事项 ​

Git ​

git-cat-file

概要

描述

选项

输出

批量输出

注意事项

Git