简体中文 ▾ Topics ▾ Latest version ▾ git-update-ref last updated in 2.53.0

名称

git-update-ref - 安全地更新存储在引用中的对象名称

概述

git update-ref [-m <原因>] [--no-deref] -d <引用> [<旧对象ID>]
git update-ref [-m <原因>] [--no-deref] [--create-reflog] <引用> <新对象ID> [<旧对象ID>]
git update-ref [-m <原因>] [--no-deref] --stdin [-z] [--batch-updates]

描述

给定两个参数后，将 <新值> 保存到 <引用> 中，并可能取消引用符号引用。 例如，git update-ref HEAD <新值> 会将当前分支的头更新为新对象。

给定三个参数，在验证 <引用> 的当前值是否与 <旧值> 匹配后，将 <新值> 保存到 <引用> 中，并可能取消引用符号引用。 例如，git update-ref refs/heads/master <新值> <旧值> 只有在 master 分支头的当前值是 <旧值> 时，才会将其更新为 <新值>。 您可以指定 40 个 "0" 或空字符串作为 <旧值> 以确保您要创建的引用不存在。

最后的参数是对象名；此命令在不带任何选项时不支持把一个符号引用更新为指向另一个引用（参见 git-symbolic-ref[1]）。但 git update-ref --stdin 提供了 symref-* 命令，因此可以在同一事务中提交普通引用和符号引用。

如果给出—​no-deref，<引用> 本身将被覆盖，而不是跟随符号指针的结果。

如果使用 -d 标志，则会在确认命名的 <引用> 仍然包含 <旧值> 后将其删除。

如果使用 --stdin，update-ref 会从标准输入读取指令，并一并执行所有修改。 指定命令格式为：

update SP <引用> SP <新对象ID> [SP <旧对象ID>] LF
create SP <引用> SP <新对象ID> LF
delete SP <引用> [SP <旧对象ID>] LF
verify SP <引用> [SP <旧对象ID>] LF
symref-update SP <引用> SP <新目标> [SP (ref SP <旧目标> | oid SP <旧对象ID>)] LF
symref-create SP <引用> SP <新目标> LF
symref-delete SP <引用> [SP <旧目标>] LF
symref-verify SP <引用> [SP <旧目标>] LF
option SP <选项> LF
start LF
prepare LF
commit LF
abort LF

如果使用 --create-reflog，update-ref 将为每个引用创建一个引用日志，即使通常不会创建引用日志。

使用 --batch-updates 时，update-ref 会以批处理方式执行更新，但允许由于用户输入无效或不正确导致的单条更新失败，并仅应用成功的更新。不过，系统相关错误（例如 I/O 失败或内存问题）会导致整批更新全部失败。任何失败的更新都会按以下格式报告：

rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF

引用包含空白的字段，就像引用 C 源代码中的字符串一样，即用双引号和反斜杠包围。 使用 40 个 "0 "字符或空字符串指定零值。 若要指定一个缺失值，请完全省略该值及其前面的 SP。

或者，使用 -z 以 NULL 结尾格式指定，不加引号：

update SP <引用> /dev/null <新对象ID> /dev/null [<旧对象ID>] NUL
create SP <引用> /dev/null <新对象ID> NUL
delete SP <引用> /dev/null [<旧对象ID>] NUL
verify SP <引用> /dev/null [<旧对象ID>] NUL
symref-update SP <引用> /dev/null <新目标> [NUL (ref NUL <旧目标> | oid NUL <旧对象ID>)] NUL
symref-create SP <引用> /dev/null <新目标> NUL
symref-delete SP <引用> [NUL <旧目标>] NUL
symref-verify SP <引用> [NUL <旧目标>] NUL
option SP <选项> NUL
start NUL
prepare NUL
commit NUL
abort NUL

在此格式中，使用 40 个 "0 " 指定零值，使用空字符串指定缺失值。

在这两种格式中，值可以以任何 Git 能识别的对象名形式指定。 任何其他格式的命令或重复的 <引用> 都会产生错误。 命令含义如下：

update

验证 <旧值> 后，将 <引用> 设置为 <新值>（如果给定）。 指定一个零 <新值>，以确保更新后引用不存在，和/或指定一个零 <旧值> 以确保更新前引用不存在。

create

在确认 <新值> 不存在后，用 <新值> 创建 <引用>。 给定的 <新值> 可能不为零。

delete

使用 <旧值> 验证 <引用> 是否存在（如果给定），然后删除 <引用>。 如果给定，<旧值> 可能不为零。

--update

验证 <旧值> 后，将 <引用> 设置为 <新值>（如果给定）。 指定一个零 <新值>，以确保更新后引用不存在，和/或指定一个零 <旧值> 以确保更新前引用不存在。

verify

对照 <旧值> 验证 <引用> 但不要更改。 如果 <旧值> 为零或缺失，则引用一定不存在。

--update

在验证符号引用 <引用> 不存在后，创建符号引用并将其指向 <新目标>。

--delete

使用 <旧值> 验证 <引用> 是否存在（如果给定），然后删除 <引用>。 如果给定，<旧值> 可能不为零。

--verify

对照 <旧值> 验证 <引用> 但不要更改。 如果 <旧值> 为零或缺失，则引用一定不存在。

option

修改命名 <引用> 的下一条命令的行为。 唯一有效的选项是 "no-deref"，以避免引用符号引用。

起点

启动事务。与非事务会话不同，如果会话在没有明确提交的情况下结束，事务会自动终止。当当前事务已提交或中止时，该命令可能会创建一个新的空事务。

准备

准备提交事务。这将为所有排队的引用更新创建锁定文件。如果一个引用无法锁定，事务将被中止。

提交

提交为该事务排队的所有引用更新，结束该事务。

中止

中止事务，如果事务处于准备状态，则释放所有锁。

如果所有 <引用> 都能同时锁定匹配的 <旧值>，则会执行所有修改。 否则，不会执行任何修改。 请注意，虽然每个 <引用> 都是以原子方式更新或删除的，但并发读者仍可能看到修改的子集。

日志更新

如果配置参数 "core.logAllRefUpdates" 为 true，且引用是 "refs/heads/"、 "refs/remotes/"、 "refs/notes/" 或类似 HEAD 或 ORIG_HEAD 的伪指；或文件 "$GIT_DIR/logs/<引用>" 存在，那么 git update-ref 就会在日志文件 "$GIT_DIR/logs/<引用>" 中添加一行，描述引用值的变化（在创建日志名之前取消引用所有符号 ref）。 日志行的格式为：

旧 sha1 值 SP 新 sha1 值 SP 提交者 LF

其中，"oldsha1" 是之前存储在 <引用> 中的 40 个字符的十六进制值，"newsha1" 是 <新值> 的 40 个字符的十六进制值，"committer" 是标准 Git committer 标识格式中的 committer 姓名、电子邮件地址和日期。

可选择使用 -m：

旧 sha1 SP 新 sha1 SP 提交值 TAB 信息 LF

其中，所有字段如上所述，“信息” 为 -m 选项提供的值。

如果当前用户无法创建新日志文件、追加现有日志文件或没有可用的提交者信息，更新将失败（不会更改 <引用>）。

注释

符号引用最初是用符号链接实现的。由于并非所有文件系统都支持符号链接，这种方式现在已被弃用。

更重要的是，它允许更新引用文件时跟踪这些符号指针，无论它们是符号链接还是这些 “普通文件符号引用”。 只有当符号链接以 "refs/" 开头时，它才会跟踪 真正 的符号链接：否则，它只会尝试读取这些符号链接，并将其作为普通文件进行更新（也就是说，它允许文件系统跟踪这些符号链接，但会将这些符号链接覆盖到其他具有普通文件名的地方）。

参见

git-symbolic-ref[1]

GIT

属于 git[1] 文档