简体中文 ▾ 主题 ▾ 最新版本 ▾ 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]

描述

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

此命令可以在两种模式下运行，取决于是否指定了 --batch 系列选项。

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

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

选项

<对象>

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

-t

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

-s

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

-e

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

-p

根据 <对象> 的类型美化输出其内容。

<类型>

通常这与 <对象> 的真实类型匹配，但也允许请求可以从给定的 <对象> 轻松解引用的类型。例如，当 <对象> 是包含该树的提交对象时请求 "tree"，或者当 <对象> 是指向该 blob 的标签对象时请求 "blob"。

--mailmap
--no-mailmap
--use-mailmap
--no-use-mailmap

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

--textconv

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

--filters

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

--filter=<过滤器规格>
--no-filter

从打印的对象列表中省略对象。这只能与批量模式之一结合使用。通过任何从标准输入读取对象的批量模式（--batch, --batch-check）明确请求的被排除对象将被报告为 "filtered"。在 --batch-all-objects 模式下被排除的对象将完全不被打印。<过滤器规格> 可以是以下之一：

形式 --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=<路径>

与 --textconv 或 --filters 配合使用，允许分别指定对象名称和路径，例如当难以确定 blob 所属的修订版本时。

--batch
--batch=<格式>

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

  • 与 --textconv 或 --filters 配合使用时，输入行必须指定路径，并以空白符分隔。详情请参见下文的 BATCH OUTPUT 部分。

  • 与 --use-mailmap 配合使用时，对于提交和标签对象，输出的内容部分显示使用 mailmap 机制替换后的身份，而输出的信息部分显示的对象大小则如同实际记录了替换后的身份一样。

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

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

  • 与 --textconv 或 --filters 配合使用时，输入行必须指定路径，并以空白符分隔。详情请参见下文的 BATCH OUTPUT 部分。

  • 与 --use-mailmap 配合使用时，对于提交和标签对象，打印的对象信息显示的对象大小如同其中记录的身份已被 mailmap 机制替换一样。

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

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

  • 与 --textconv 或 --filters 配合使用时，输入行必须指定路径，并以空白符分隔。详情请参见下文的 BATCH OUTPUT 部分。

  • 与 --use-mailmap 配合使用时，对于提交和标签对象，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 进行交互式读写。使用此选项后，输出将使用正常的标准输入输出缓冲；在对大量对象调用 --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) 的占位符，后跟换行符。可用的 atom 有：

objectname

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

objecttype

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

objectmode

如果指定的对象具有模式信息（如树或索引条目），则为以八进制整数表示的模式。否则为空字符串。

objectsize

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

objectsize:disk

对象在磁盘上占用的字节大小。请参阅下文 CAVEATS 部分中关于磁盘大小的说明。

deltabase

如果对象以磁盘增量（delta）形式存储，则展开为增量基准对象名称的全十六进制表示。否则，展开为全零 OID（空 OID）。参见下文的 CAVEATS。

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

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

<object> SP missing LF

如果在标准输入指定了一个被 --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] 套件的一部分