簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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] 套件的一部分