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