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

名称

git-update-ref - 安全地更新存储在 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>，以确保您正在创建的 ref 不存在。

最后一个参数是对象名称；此命令在没有选项的情况下不支持将符号引用更新为指向另一个引用（请参阅 git-symbolic-ref[1]）。但是 git update-ref --stdin 具有 symref-* 命令，以便常规引用和符号引用可以在同一事务中提交。

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

使用 -d，它会在验证 <ref> 仍包含 <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，即使通常不会创建。

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

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

create

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

delete

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

symref-update

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

verify

验证 <ref> 与 <old-oid>，但不要更改它。如果 <old-oid> 为零或缺失，则 ref 必须不存在。

symref-create：创建符号引用 <ref> 并设置 <new-target>，在验证它不存在后。

symref-delete

删除 <ref>，在验证它存在并具有 <old-target>（如果给定）后。

symref-verify

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

option

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

start

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

prepare

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

commit

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

abort

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

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

日志更新

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

注意事项

符号引用最初是使用符号链接实现的。现在不推荐使用此方法，因为并非所有文件系统都支持符号链接。

此命令仅在以 "refs/" 开头时跟随 **真实** 的符号链接；否则，它只会尝试读取它们并将它们作为常规文件更新（即，它将允许文件系统跟随它们，但会用普通文件名覆盖指向其他地方的此类符号链接）。

另请参阅

git-symbolic-ref[1]

GIT

Git[1] 套件的一部分