Git
英语 ▾ 主题 ▾ 最新版本 ▾ git-update-ref 最后更新于 2.46.0

名称

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

概要

git update-ref [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])

描述

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

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

它还允许“ref”文件成为指向另一个 ref 文件的符号指针，方法是开头使用四个字节的头序列“ref:”。

更重要的是，它允许更新 ref 文件以遵循这些符号指针，无论它们是符号链接还是这些“常规文件符号 ref”。它仅在符号链接以“refs/”开头时才遵循**实际**符号链接：否则，它将尝试读取它们并将其作为常规文件更新（即它将允许文件系统跟踪它们，但会将此类符号链接覆盖到其他地方使用常规文件名）。

如果给出 --no-deref，则会覆盖 <ref> 本身，而不是遵循符号指针的结果。

通常，使用

git update-ref HEAD "$head"

应该比执行

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

要安全得多，从符号链接跟踪的角度和错误检查的角度来看都是如此。符号链接的“refs/”规则意味着指向树“外部”的符号链接是安全的：它们将被跟踪以供读取，但不会被跟踪以供写入（因此，如果您创建了一个符号链接树，我们将永远不会通过 ref 符号链接写入其他树，因为您已经复制了整个存档）。

使用 -d 标志，它在验证它仍然包含 <old-oid> 后会删除命名的 <ref>。

使用 --stdin，update-ref 从标准输入读取指令并一起执行所有修改。指定以下形式的命令

update SP <ref> SP <new-oid> [SP <old-oid>] LF
create SP <ref> SP <new-oid> LF
delete SP <ref> [SP <old-oid>] LF
verify SP <ref> [SP <old-oid>] LF
symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
symref-create SP <ref> SP <new-target> LF
symref-delete SP <ref> [SP <old-target>] LF
symref-verify SP <ref> [SP <old-target>] LF
option SP <opt> LF
start LF
prepare LF
commit LF
abort LF

使用 --create-reflog，update-ref 将为每个 ref 创建 reflog，即使通常不会创建 reflog。

将包含空格的字段引用为 C 源代码中的字符串；即，用双引号括起来并使用反斜杠转义。使用 40 个“0”字符或空字符串指定零值。要指定缺失值，请省略该值及其前面的 SP。

或者，使用 -z 以 NUL 终止的格式指定，无需引用

update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
create SP <ref> NUL <new-oid> NUL
delete SP <ref> NUL [<old-oid>] NUL
verify SP <ref> NUL [<old-oid>] NUL
symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
symref-create SP <ref> NUL <new-target> NUL
symref-delete SP <ref> [NUL <old-target>] NUL
symref-verify SP <ref> [NUL <old-target>] NUL
option SP <opt> NUL
start NUL
prepare NUL
commit NUL
abort NUL

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

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

更新

在验证 <old-oid> 后（如果给出）将 <ref> 设置为 <new-oid>。指定零 <new-oid> 以确保 ref 在更新后不存在，或指定零 <old-oid> 以确保 ref 在更新前不存在。

创建

在验证它不存在后，使用 <new-oid> 创建 <ref>。给定的 <new-oid> 不能为零。

删除

在验证它存在且为 <old-oid> 后（如果给出）删除 <ref>。如果给出，<old-oid> 不能为零。

symref-update

在验证 <old-target> 或 <old-oid>（如果给出）后，将 <ref> 设置为 <new-target>。指定零 <old-oid> 以确保 ref 在更新前不存在。

验证

验证 <ref> 是否与 <old-oid> 相符，但不更改它。如果 <old-oid> 为零或缺失，则 ref 不得存在。

symref-create: 在验证它不存在后，使用 <new-target> 创建符号 ref <ref>。

symref-delete

在验证它存在且为 <old-target> 后（如果给出）删除 <ref>。

symref-verify

验证符号 <ref> 是否与 <old-target> 相符，但不更改它。如果 <old-target> 缺失，则 ref 不得存在。只能在 no-deref 模式下使用。

选项

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

开始

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

准备

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

提交

提交为事务排队的全部引用更新，结束事务。

中止

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

如果所有 <ref> 都能同时使用匹配的 <old-oid> 锁定，则会执行所有修改。否则，不会执行任何修改。请注意，虽然每个 <ref> 都是原子更新或删除的，但并发读取器可能仍然会看到部分修改。

记录更新

如果配置参数“core.logAllRefUpdates”为 true，并且 ref 是“refs/heads/”、“refs/remotes/”、“refs/notes/”下的 ref 或类似 HEAD 或 ORIG_HEAD 的伪 ref；或者文件“$GIT_DIR/logs/<ref>”存在，则 git update-ref 将在日志文件“$GIT_DIR/logs/<ref>”中追加一行（取消对所有符号 ref 的引用，然后创建日志名称），描述 ref 值的更改。日志行格式如下

oldsha1 SP newsha1 SP committer LF

其中“oldsha1”是先前存储在 <ref> 中的 40 个字符的十六进制值，“newsha1”是 <new-oid> 的 40 个字符的十六进制值，“committer”是提交者的名称、电子邮件地址和日期，采用标准的 Git 提交者标识格式。

可选地使用 -m

oldsha1 SP newsha1 SP committer TAB message LF

其中所有字段的描述如上所示，“message”是提供给 -m 选项的值。

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

GIT

是 git[1] 套件的一部分

scroll-to-top