HOWTO · Git
Git Push --force-with-lease 與 Git Push --force
比較 git push --force 與 git push --force-with-lease,然後選擇更安全的方式,在改寫歷史後更新遠端分支。
本頁內容
執行 rebase 或 amend 後,已發佈的提交會發生變化;如果遠端分支無法從本地分支快進更新,普通 push 可能會被拒絕。git push --force 和 git push --force-with-lease 都能取代遠端分支的頂端提交。兩者的區別在於,Git 是否會在更新前檢查預期的遠端值。若確實要改寫歷史,優先使用帶 lease 的形式;如果 Git 拒絕了 push,再檢查並協調遠端狀態。
git push --force 的運作方式
普通 push 要求分支向前更新,以此保護遠端提交。git push --force 會對正在推送的參照取消這項保護:遠端分支會被設為你指定的提交,即使這會讓一些提交從分支可見歷史中消失。如果隊友推送了你尚未納入本地歷史的工作,這些提交可能會無法再從該分支存取。
該命令的作用範圍由目標決定。例如,git push --force origin feature 會更新 origin 上的 feature 分支;如果沒有明確寫出分支名稱,就不容易看清哪些參照會受影響。只有在你確實打算取代分支歷史,並且已與所有使用該分支的人協調好時,才使用 force push。它不會產生合併衝突,也不會替你合併遠端提交。
git push --force-with-lease 的運作方式
git push --force-with-lease origin feature 同樣允許非快進更新,但會先檢查遠端分支是否仍指向預期的值。常見情況下,Git 會根據本地的遠端追蹤參照來確定這個預期值,例如 origin/feature。如果伺服器上的分支值與之不同,Git 會拒絕更新,而不是取代它。
這項檢查很有用,但不能證明沒有人推送你尚未看到的工作。如果背景 fetch 在你上次檢查後更新了 origin/feature,預設 lease 可能會基於這個剛取得的值接受歷史改寫。明確指定預期物件 ID,可以讓比較更具針對性:git push --force-with-lease=refs/heads/feature:<expected-object-id> origin HEAD:refs/heads/feature。應將預期值的取得和檢查納入團隊流程;不要在沒確認物件 ID 所代表內容的情況下直接複製使用。
改寫歷史後使用 --force-with-lease
假設共享分支原本是 A---B---C,協作者在 C 之後添加了 D,而你將本地工作 rebase 後得到 A---B---C'。此時,本地的 C' 和遠端的 D 分別代表不同的分支頂端。如果你預期的遠端狀態仍是 C,lease 的作用是避免你悄悄覆蓋 D。
先檢查分支並取得遠端的目前狀態,再決定是否要把協作者的提交納入改寫後的歷史。你可以將自己的工作 rebase 到剛取得的分支上,也可以與團隊協商其他整合方案。解決並檢查好歷史後,再用 lease 推送預期結果。如果 lease 拒絕了 push,就重新 fetch 並檢查;不要立刻改用 --force 重試。
執行下面這個獨立範例,可以建立本地分支、將其推送到臨時裸倉庫、修改分支頂端的提交,再使用 lease 更新遠端:
set -e
root="$(mktemp -d)"
trap 'rm -rf "$root"' EXIT
git init --bare "$root/remote.git" >/dev/null 2>&1
git init -b feature "$root/work" >/dev/null 2>&1
cd "$root/work"
git config user.name "Example Developer"
git config user.email "developer@example.com"
printf 'first version\n' > README.md
git add README.md
git commit -m "Add first version" >/dev/null 2>&1
git remote add origin "$root/remote.git"
git push -u origin feature >/dev/null 2>&1
git commit --amend -m "Rewrite first version" >/dev/null 2>&1
git push --force-with-lease origin feature >/dev/null 2>&1
範例中的路徑都是臨時路徑,腳本結束時會刪除其測試環境。在真實倉庫中替換共享歷史之前,請先檢查相關提交,並與協作者協調。
安全選擇強制推送方式
如果個人分支沒有協作者,而且你確實打算取代遠端分支頂端,直接 force push 可能是可接受的。對於共享分支,應先檢查預期的遠端狀態並協調好歷史改寫,再選擇 --force-with-lease。如果可以透過 pull request 或其他審查流程避免改寫共享分支,優先考慮這些做法。
明確指定遠端和分支,做決定前先 fetch,並在推送前檢查提交圖。lease 拒絕更新是一個安全訊號:將本地分支與剛取得的遠端分支進行比較,保留需要的提交,並在確認它們應如何納入歷史後再重試。定期同步可以減少意外,但不能取代對即將發佈的提交歷史的檢查。
復原或預防提交遺失
如果 force push 讓某個提交從分支頂端消失,請先停止清理操作,並尋找是否還有保留該提交的參照。在本地克隆中,git reflog 可能會顯示近期的分支位置;其他協作者的克隆、遠端備份或程式碼託管服務的復原功能也可能保留著該提交。如果找到它,先在該提交處建立一個分支,再決定如何復原或整合。reflog 項目會過期,而且僅保存在本地,因此無法保證一定能復原。
為避免遺失提交,應事先約定誰可以改寫共享分支,在更新前通知協作者,並在需要審查改寫時保留一個已知參照。lease 可以減少一類意外覆蓋;明確協調並確認有可用的復原點,則能應對它無法偵測的風險。
常見問題
git push --force 和 git push --force-with-lease 有什麼區別? 前者會在不檢查遠端目前值的情況下取代遠端參照。後者會檢查預期值;如果遠端與之不符,就會拒絕更新。
什麼時候可以使用 git push --force? 只有在你確實打算取代目標分支的頂端、清楚哪些提交可能會從該分支消失,並且已與受影響的協作者協調好時,才使用它。對於共享工作,優先使用 lease,並檢查其預期狀態。
在共享分支上強制推送有危險嗎? 這可能會讓提交從分支歷史中消失,並影響協作者的工作。如果遠端與預期值不同,lease 可以幫助避免覆蓋;但如果預設預期值被你沒有檢查過的 fetch 更新,它也可能無法發現問題。
如何減少衝突或意外? 先 fetch 並檢查遠端,在適當情況下將協作者的提交整合到改寫後的歷史中,提前溝通計畫,並對共享變更使用審查流程。
強制推送後可以復原嗎? 沒有自動復原的方法。你可能可以透過 reflog、其他克隆或程式碼託管服務的復原功能找到先前的提交,然後建立一個參照並協調復原。能否復原取決於該提交是否仍有參照保留。