Git
英文 ▾ 主題 ▾ 最新版本 ▾ git-update-ref 最後更新於 2.46.0

名稱

git-update-ref - 安全地更新儲存在 ref 中的物件名稱

概要

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

描述

給定兩個參數，將 <new-oid> 儲存在 <ref> 中，可能會取消參照符號 refs。 例如，git update-ref HEAD <new-oid> 會將目前分支的 HEAD 更新為新的物件。

給定三個參數，將 <new-oid> 儲存在 <ref> 中，可能會取消參照符號 refs，並在驗證 <ref> 的目前值是否符合 <old-oid> 後進行。例如，git update-ref refs/heads/master <new-oid> <old-oid> 只會在 master 分支的目前值為 <old-oid> 時，將其 HEAD 更新為 <new-oid>。您可以將 40 個 "0" 或空字串指定為 <old-oid>，以確保您正在建立的 ref 不存在。

它還允許 "ref" 檔案成為指向另一個 ref 檔案的符號指標，方法是以 "ref:" 的四位元組標頭序列開頭。

更重要的是，它允許 ref 檔案的更新遵循這些符號指標，無論它們是符號連結還是這些「一般檔案符號 refs」。只有當它們以 "refs/" 開頭時，它才會追蹤真實的符號連結：否則，它只會嘗試讀取它們並將它們作為一般檔案更新（也就是說，它將允許檔案系統追蹤它們，但會將指向其他位置的此類符號連結覆寫為一般檔案名稱）。

如果指定 --no-deref，則會覆寫 <ref> 本身，而不是追蹤符號指標的結果。

一般來說，使用

git update-ref HEAD "$head"

應該比執行

echo "$head" > "$GIT_DIR/HEAD"

在符號連結追蹤的觀點和錯誤檢查的觀點上，都安全得多。符號連結的 "refs/" 規則表示指向樹狀結構「外部」的符號連結是安全的：它們將被追蹤以進行讀取，但不進行寫入（因此，如果您透過建立符號連結樹狀結構複製了整個封存，我們將永遠不會透過 ref 符號連結寫入到其他樹狀結構）。

使用 -d 旗標，它會在驗證名為 <ref> 的 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，即使通常不會建立 reflog，update-ref 也會為每個 ref 建立一個 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> 都會產生錯誤。命令意義如下

update

在驗證 <old-oid>（如果已給定）之後，將 <ref> 設定為 <new-oid>。指定零 <new-oid> 以確保在更新後 ref 不存在，和/或指定零 <old-oid> 以確保在更新之前 ref 不存在。

create

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

delete

在驗證 <ref> 存在並具有 <old-oid>（如果已給定）後，刪除 <ref>。如果已給定，<old-oid> 不得為零。

symref-update

在驗證 <old-target> 或 <old-oid>（如果已給定）後，將 <ref> 設定為 <new-target>。指定零 <old-oid> 以確保在更新之前 ref 不存在。

verify

根據 <old-oid> 驗證 <ref>，但不變更它。如果 <old-oid> 為零或遺失，則 ref 必須不存在。

symref-create：在驗證符號 ref <ref> 不存在後，使用 <new-target> 建立該 ref。

symref-delete

在驗證 <ref> 存在並具有 <old-target>（如果已給定）後，刪除 <ref>。

symref-verify

根據 <old-target> 驗證符號 <ref>，但不變更它。如果 <old-target> 遺失，則 ref 必須不存在。只能在 no-deref 模式中使用。

option

修改下一個命名 <ref> 的命令的行為。唯一有效的選項是 no-deref，以避免取消參照符號 ref。

start

開始一個交易。與非交易式工作階段相反，如果工作階段在沒有明確提交的情況下結束，則交易會自動中止。當目前的交易已經提交或中止時，此命令可能會建立一個新的空交易。

prepare

準備提交交易。這會為所有已排隊的參考更新建立鎖定檔案。如果無法鎖定一個參考，則交易將會中止。

commit

提交為交易排隊的所有參考更新，結束交易。

abort

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

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

記錄更新

如果組態參數 "core.logAllRefUpdates" 為 true，且 ref 是 "refs/heads/"、"refs/remotes/"、"refs/notes/" 底下的 ref 之一，或是像 HEAD 或 ORIG_HEAD 這類的虛擬 ref；或者如果檔案 "$GIT_DIR/logs/<ref>" 存在，則 git update-ref 會將一行附加到記錄檔 "$GIT_DIR/logs/<ref>"（在建立記錄名稱之前取消參照所有符號 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>）。

GIT

屬於 git[1] 套件的一部分

scroll-to-top