English ▾ 主題 ▾ 最新版本 ▾ git-update-ref 最後更新於 2.53.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> 中，並可能解引用符號引用（symbolic refs）。例如：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 時，即使通常不會建立 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

在驗證 <ref> 不存在後，使用 <new-oid> 建立它。給定的 <new-oid> 不可為零。

delete

在驗證存在該 <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

在驗證存在該 <ref> 且其值為 <old-target>（若有提供）後，將其刪除。

symref-verify

針對 <old-target> 驗證符號 <ref> 但不進行變更。若 <old-target> 缺失，則該引用必須不存在。僅能在 no-deref 模式下使用。

option

修改下一個指定 <ref> 的指令行為。唯一有效的選項是 no-deref，用於避免解引用符號引用。

start

開始一個交易。與非交易式對話不同，若對話在沒有明確提交的情況下結束，交易將自動中止。當目前的交易已提交或中止時，此指令可以建立一個新的空交易。

prepare

準備提交交易。這將為所有排隊的引用更新建立鎖定檔案。若有一個引用無法鎖定，交易將中止。

commit

提交所有交易排隊的引用更新，並結束交易。

abort

中止交易，若交易處於準備狀態，則釋放所有鎖定。

若所有 <ref> 都能同時被鎖定且符合 <old-oid>，則會執行所有修改。否則，不會執行任何修改。請注意，雖然每個個別的 <ref> 是以原子方式更新或刪除的，但並行的讀取者仍可能看到部分修改。

更新記錄（LOGGING UPDATES）

若組態參數「core.logAllRefUpdates」為 true，且該引用位於「refs/heads/」、「refs/remotes/」、「refs/notes/」之下，或是類似 HEAD 或 ORIG_HEAD 的偽引用（pseudoref）；或者檔案「$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] 套件的一部分