English ▾ 主题 ▾ 最新版本 ▾ git-update-ref 上次更新于 2.48.0

名称

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

概要

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

描述

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

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

最后的参数是对象名称;此命令在没有任何选项的情况下不支持更新符号引用以指向另一个引用(请参阅 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 将为每个引用创建一个 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> 以确保更新后引用不存在,和/或指定零 <old-oid> 以确保更新前引用不存在。

创建

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

删除

在验证 <ref> 存在并且具有 <old-oid>(如果已给出)之后,删除 <ref>。 如果已给出,则 <old-oid> 不得为零。

symref-update

在验证 <old-target> 或 <old-oid>(如果已给出)之后,将 <ref> 设置为 <new-target>。 指定零 <old-oid> 以确保更新前引用不存在。

验证

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

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

symref-delete

在验证 <ref> 存在并且具有 <old-target>(如果已给出)之后,删除 <ref>。

symref-verify

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

选项

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

开始

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

准备

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

提交

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

中止

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

如果所有 <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

属于 git[1] 套件的一部分

scroll-to-top