简体中文 ▾ 主题 ▾ 最新版本 ▾ git-update-ref 最后更新于 2.53.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 将为每个引用创建引用日志，即使通常情况下不会创建。

使用 --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

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

delete

在验证引用存在且值为 <old-oid>（如果已给定）后，删除 <ref>。如果给定，<old-oid> 不得为零。

symref-update

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

verify

针对 <old-oid> 验证 <ref>，但不更改它。如果 <old-oid> 为零或缺失，则该引用必须不存在。

symref-create

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

symref-delete

在验证引用存在且指向 <old-target>（如果已给定）后，删除 <ref>。

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] 套件的一部分