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

名称

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

概述

git update-ref [-m <原因>] [--no-deref] (-d <引用> [<旧值>] | [--create-reflog] <引用> <新值> [<旧值>] | --stdin [-z])

描述

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

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

它还允许一个 “引用” 文件以 "ref: " 的四字节头序列作为另一个引用文件的符号指针。

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

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

一般来说，使用

git update-ref HEAD "$head"

应该比下面的做法安全得多

echo "$head" > "$GIT_DIR/HEAD"

和错误检查的角度来看都是如此。 符号链接的 "refs/" 规则意味着指向树 “外部” 的符号链接是安全的：它们在读取时会被跟踪，但在写入时不会被跟踪（因此，如果你通过创建一个符号链接目录复制了整个归档文件，我们永远不会通过引用符号链接写入其他目录树）。

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

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

update SP <引用> SP <新值> [SP <旧值>] LF
create SP <引用> SP <新值> LF
delete SP <引用> [SP <旧值>] LF
verify SP <引用> [SP <旧值>] LF
option SP <选项> LF
start LF
prepare LF
commit LF
abort LF

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

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

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

update SP <引用> NUL <新值> NUL [<旧值>] NUL
create SP <引用> NUL <新值> NUL
delete SP <引用> NUL [<旧值>] NUL
verify SP <引用> NUL [<旧值>] NUL
option SP <选项> NUL
start NUL
prepare NUL
commit NUL
abort NUL

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

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

update

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

create

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

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 选项提供的值。

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

GIT

属于 git[1] 文档

scroll-to-top