简体中文 ▾ 主题 ▾ 最新版本 ▾ git-update-ref 最后更新于 2.50.0

名称

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

概要

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

描述

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

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

最后的参数是对象名称；此命令在不带任何选项的情况下不支持更新符号引用以指向另一个引用（参见 git-symbolic-ref[1]）。但 git update-ref --stdin 确实包含 symref-* 命令，因此常规引用和符号引用可以在同一事务中提交。

如果指定了 --no-deref，则 <ref> 本身将被覆盖，而不是跟随符号指针的结果。

使用 -d，它会在验证指定 <ref> 仍包含 <old-oid> 后将其删除。

使用 --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 将为每个引用创建 reflog，即使通常不会创建。

使用 --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 以 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> 都会产生错误。命令含义如下：

update

如果给定 <old-oid>，则在验证其后将 <ref> 设置为 <new-oid>。指定零 <new-oid> 可确保更新后引用不存在，和/或指定零 <old-oid> 可确保更新前引用不存在。

create

创建 <ref> 并使用 <new-oid>，前提是验证它不存在。给定的 <new-oid> 不得为零。

delete

如果给定 <old-oid>，则在验证 <ref> 存在且包含 <old-oid> 后将其删除。如果给定，<old-oid> 不得为零。

symref-update

如果给定 <old-target> 或 <old-oid>，则在验证其后将 <ref> 设置为 <new-target>。指定零 <old-oid> 可确保在更新前引用不存在。

verify

根据 <old-oid> 验证 <ref>，但不更改它。如果 <old-oid> 为零或缺失，则引用不得存在。

symref-create: 创建符号引用 <ref> 并使用 <new-target>，前提是验证它不存在。

symref-delete

如果给定 <old-target>，则在验证 <ref> 存在且包含 <old-target> 后将其删除。

symref-verify

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

option

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

start

开始一个事务。与非事务性会话不同，如果会话在没有显式提交的情况下结束，事务将自动中止。当当前事务已提交或已中止时，此命令可能会创建一个新的空事务。

prepare

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

commit

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

abort

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

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

更新日志

如果配置参数“core.logAllRefUpdates”为 true，且引用位于“refs/heads/”、“refs/remotes/”、“refs/notes/”之下，或是一个像 HEAD 或 ORIG_HEAD 这样的伪引用；或者文件“$GIT_DIR/logs/<ref>”存在，则 git update-ref 将在日志文件“$GIT_DIR/logs/<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>）。

注意事项

符号引用最初是使用符号链接实现的。由于并非所有文件系统都支持符号链接，因此现在已弃用此方法。

此命令仅在符号链接以“refs/”开头时才跟随真正的符号链接：否则它只会尝试将它们作为常规文件读取和更新（即，它将允许文件系统跟随它们，但会将此类指向其他位置的符号链接覆盖为常规文件名）。

另请参阅

git-symbolic-ref[1]

GIT

Git[1] 套件的一部分

scroll-to-top