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 系列选项。

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

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

选项

<对象>

The name of the object to show. For a more complete list of ways to spell object names, see the "SPECIFYING REVISIONS" section in gitrevisions[7].

-t

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

-s

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

-e

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

-p

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

<类型>

Typically this matches the real type of <object> but asking for a type that can trivially be dereferenced from the given <object> is also permitted. An example is to ask for a "tree" with <object> being a commit object that contains it, or to ask for a "blob" with <object> being a tag object that points at it.

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

Use mailmap file to map author, committer and tagger names and email addresses to canonical real names and email addresses. See 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

Instead of reading a list of objects on stdin, perform the requested batch operation on all objects in the repository and any alternate object stores (not just reachable objects). Requires --batch or --batch-check be specified. By default, the objects are visited in order sorted by their hashes; see also --unordered below. Objects are presented as-is, without respecting the "replace" mechanism of git-replace[1].

--buffer

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

--unordered

When --batch-all-objects is in use, visit objects in an order which may be more efficient for accessing the object contents than hash order. The exact details of the order are unspecified, but if you do not require a specific order, this should generally result in faster output, especially with --batch. Note that cat-file will still show each object only once, even if it is stored multiple times in the repository.

--allow-unknown-type

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

With --batch or --batch-check, follow symlinks inside the repository when requesting objects with extended SHA-1 expressions of the form tree-ish:path-in-tree. Instead of providing output about the link itself, provide output about the linked-to object. If a symlink points outside the tree-ish (e.g. a link to /foo or a root-level link to ../foo), the portion of the link which is outside the tree will be printed.

如果指定的是索引中的对象(例如,: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

Without --follow-symlinks, these would print data about the symlink itself. In the case of HEAD:link, you would see

4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1

plinkalink 都指向树外,因此将分别打印:

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-checkcat-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

If the object is stored as a delta on-disk, this expands to the full hex representation of the delta base object name. Otherwise, expands to the null OID (all zeroes). See CAVEATS below.

rest

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

If no format is specified, the default format is %(objectname) %(objecttype) %(objectsize).

如果指定了 --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

The symlink will either be absolute (beginning with a /), or relative to the tree root. For instance, if dir/link points to ../../foo, then <symlink> will be ../foo. <size> is the size of the symlink in bytes.

如果使用 --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