简体中文 ▾ 主题 ▾ 最新版本 ▾ git-refs 最后更新于 2.54.0

名称

git-refs - 对引用（refs）的底层访问

概要

git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
git refs verify [--strict] [--verbose]
git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
		   [(--sort=<key>)…​] [--format=<format>]
		   [--include-root-refs] [--points-at=<object>]
		   [--merged[=<object>]] [--no-merged[=<object>]]
		   [--contains[=<object>]] [--no-contains[=<object>]]
		   [(--exclude=<pattern>)…​] [--start-after=<marker>]
		   [ --stdin | (<pattern>...)]
git refs exists <ref>
git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]

描述

此命令提供对引用的底层访问。

命令

migrate

在不同格式之间迁移引用存储。

verify

验证引用数据库的一致性。

list

列出仓库中的引用，支持过滤、格式化和排序。此子命令是 git-for-each-ref[1] 的别名，功能完全相同。

exists

检查给定的引用是否存在。如果存在返回退出码 0，如果缺失返回 2，如果查找引用时因引用缺失以外的错误失败则返回 1。此操作不验证引用是否解析为实际对象。

optimize

优化引用以提高仓库性能并减少磁盘使用。此子命令是 git-pack-refs[1] 的别名，功能完全相同。

选项

以下选项特定于 git refs migrate

--ref-format=<format>

要将引用存储迁移到的引用格式。可以是以下之一：

files

用于带 packed-refs 的松散文件。这是默认格式。

reftable

用于 reftable 格式。

--dry-run

执行迁移，但不修改仓库。迁移后的引用将被写入一个单独的目录，可以分别进行检查。目录名称将在标准输出上报告。这可以在执行实际迁移之前，用于仔细检查迁移是否按预期工作。

--reflog
--no-reflog

选择将引用日志（reflog）数据迁移到新后端，还是将其丢弃。默认为 "--reflog"，即执行迁移。

以下选项特定于 git refs verify

--strict

启用更严格的错误检查。这将导致警告被报告为错误。参见 git-fsck[1]。

--verbose

在验证引用数据库的一致性时，输出详细信息。

以下选项特定于 git refs list

<pattern>...

如果提供了一个或多个 <pattern> 参数，则仅显示与至少一个模式匹配的引用，使用 fnmatch(3) 或按字面匹配（后者指完全匹配或从起始位置到斜杠处匹配）。

--stdin

从标准输入读取模式列表，而不是从参数列表中读取。

--count=<count>

在显示 <count> 个引用后停止。

--sort=<key>

按字段名 <key> 排序。前缀 - 表示按值的降序排序。如果不指定，则使用 refname。您可以多次使用 --sort=<key> 选项，在这种情况下，最后一个键将成为主键。

--format[=<format>]

一个字符串，用于从正在显示的引用及其指向的对象中插入 %(fieldname)。此外，字面字符串 %% 将呈现为 %，而 %xx（其中 xx 是十六进制数字）将呈现为十六进制代码为 xx 的字符。例如，%00 插入为 \0 (NUL)，%09 插入为 \t (TAB)，%0a 插入为 \n (LF)。

如果不指定，<format> 默认为 %(objectname) SPC %(objecttype) TAB %(refname)。

--color[=<when>]

遵守 --format 选项中指定的颜色。<when> 字段必须是 always、never 或 auto 之一（如果未提供 <when>，则表现为如同指定了 always）。

--shell
--perl
--python
--tcl

如果给出，替代 %(fieldname) 占位符的字符串将被引用，使其成为适合指定宿主语言的字符串字面量。旨在生成一个可以直接被 "eval" 执行的脚本片段。

--points-at=<object>

仅列出指向给定对象的引用。

--merged[=<object>]

仅列出其末端可从指定提交到达的引用（如果未指定，则为 HEAD）。

--no-merged[=<object>]

仅列出其末端无法从 <object> 到达的引用（如果未指定，则为 HEAD）。

--contains[=<object>]

仅列出包含 <object> 的引用（如果未指定，则为 HEAD）。

--no-contains[=<object>]

仅列出不包含 <object> 的引用（如果未指定，则为 HEAD）。

--ignore-case

引用排序和过滤不区分大小写。

--omit-empty

在格式化引用中，如果格式扩展为空字符串，则不在其后打印换行符。

--exclude=<excluded-pattern>

如果给出一个或多个 --exclude 选项，则仅显示与任何 <excluded-pattern> 参数不匹配的引用。匹配规则与上述 <pattern> 相同。

--include-root-refs

除常规引用外，还列出根引用（HEAD 和伪引用）。

--start-after=<marker>

允许通过跳过直到（并包含）指定标记的引用来进行输出分页。分页时应注意，引用可能在调用之间被删除、修改或添加。输出仅产生那些在字典顺序上位于标记之后的引用。输出从按字母顺序排列在标记之后的第一个引用开始。不能与 --sort=<key> 或 --stdin 选项，或用于限制引用的 <pattern> 参数一起使用。

以下选项特定于 git refs optimize

--all

该命令默认打包所有标签和已打包的引用，而忽略其他引用。这是因为分支被认为是活跃开发的，打包它们的末端对性能没有帮助。此选项会导致所有引用也被打包，隐藏引用、损坏引用和符号引用除外。对于拥有许多具有历史意义分支的仓库非常有用。

--no-prune

该命令通常在打包后删除 $GIT_DIR/refs 层级下的松散引用。此选项告知它不要删除。

--auto

根据引用数据库的当前状态，按需打包引用。其行为取决于仓库使用的引用格式，并且在未来可能会发生变化。

  • "files"：松散引用根据松散引用与 packed-refs 文件大小的比率被打包进 packed-refs 文件中。packed-refs 文件越大，在进行重新打包前需要存在的松散引用就越多。

  • "reftable"：表被压缩以形成几何序列。对于两个表 N 和 N+1（N+1 较新），这保持了 N 至少是 N+1 两倍大的属性。仅压缩违反此属性的表。

--include <pattern>

根据 glob(7) 模式打包引用。重复此选项会累积包含模式。如果一个引用既被 --include 包含，又被 --exclude 包含，则 --exclude 优先。使用 --include 将默认阻止所有标签被包含。符号引用和损坏引用将永远不会被打包。当与 --all 一起使用时，它将不起作用。使用 --no-include 来清除并重置模式列表。

--exclude <pattern>

不要打包匹配给定 glob(7) 模式的引用。重复此选项会累积排除模式。使用 --no-exclude 来清除并重置模式列表。如果引用已打包，使用 --exclude 包含它也不会解包它。

当与 --all 一起使用时，仅打包不匹配任何所提供 --exclude 模式的松散引用。

当与 --include 一起使用时，提供给 --include 的引用（减去提供给 --exclude 的引用）将被打包。

已知限制

引用格式迁移在当前形式下有几个已知限制：

  • 无法迁移拥有工作树（worktrees）的仓库。

  • 在正在进行的迁移过程中，无法阻止对仓库的并发写入。并发写入可能导致迁移状态不一致。用户需要在更高级别上阻止写入。如果您的仓库已注册用于计划性维护，建议首先使用 git-maintenance(1) 取消注册。

这些限制将来可能会被取消。

GIT

Git[1] 套件的一部分