ELI5 · GitHub

合併的時候撞到衝突,會怎樣?

gh pr merge --squash --delete-branch
😌
什麼都不會發生

指令直接失敗、印一行紅字就結束。
你的電腦一個字都不會變,不用收拾任何東西。

為什麼你這邊不會弄髒?

因為合併不是在你的電腦上做的。 這道指令只是打一通電話給 GitHub,叫它去合併。

💻
你的電腦

只負責打電話
沒有動到任何檔案,
工作目錄乾乾淨淨。

幫我合併 #5
不行,合不起來
🌐
GitHub 的伺服器

它家試著合併。
發現兩邊改到同一行,
算不出結果就回絕你。

跟你熟悉的那個 merge 差在哪

🍳
git merge
在你家廚房煮

東西全擺在你的流理台上。撞到衝突,鍋碗瓢盆就攤在那裡, 檔案裡會被塞進一堆 <<<<<<< 記號。

你要收拾:不是解完它,就是 git merge --abort 把現場還原。

🏭
gh pr merge
送去遠方的工廠做

你只是送了一張單子過去。工廠做不出來就把單子退回來, 你家流理台從頭到尾沒被碰過。

你不用收拾:沒有半個檔案被改,沒有狀態要還原。

螢幕上會出現這三行

第一行是真話。後面兩行是陷阱。

X Pull request owner/repo#5 is not mergeable: the merge commit cannot be cleanly created.
✓ 真話
「合不起來」
To have the pull request merged after all the requirements have been met, add the `--auto` flag.
⚠ 陷阱
照做沒用
To use administrator privileges to immediately merge the pull request, add the `--admin` flag.
⚠ 陷阱
照做沒用

這兩行建議不是為你寫的。
合併失敗有很多種原因,而 gh 不管哪一種都印同一組建議

那兩個旗標其實在做什麼

--auto

它的意思是「排隊等」——條件都湊齊的那一刻,自動幫我合併。 它不會去解決任何事,只是站在門口等門開。

衝突不會自己好。門永遠不開,你就排到天荒地老。

🔑
--admin

它的意思是「我有鑰匙」——用管理員身分打開規則鎖, 比如「一定要有人審核」「CI 一定要綠」這種人訂的門檻。

衝突不是一道鎖,是兩張紙寫了不一樣的字、沒人知道該留哪張。鑰匙開不了「沒有答案」。

順便說:--delete-branch 也不會發生。 合併失敗,程式在前一步就退場了,分支原封不動還在那裡。

真正的解法:把衝突搬回家解

GitHub 不會幫你決定該留誰的版本。只有你能決定,所以得在你的電腦上做。

1
先把 main 上的新東西抓下來
衝突的來源就是別人已經合併進 main 的改動。要解它,你得先拿到它。
2
在自己的分支上解掉衝突
打開被標記的檔案,決定每一處要留哪一邊,把 <<<<<<< 那些記號清乾淨。
3
推上去,再跑一次原本那道指令
GitHub 重新算一次,發現這次合得起來,就會照你原本要的 squash 合併並刪掉分支。

實際打的指令長這樣:

git switch main
git pull                        # 把別人合併進去的新東西抓下來
git switch 你的分支
git rebase main                 # 疊到最新的 main 上;這時會停下來叫你解衝突
git add .                       # 解完之後標記「這幾個檔我處理好了」
git rebase --continue
git push --force-with-lease     # rebase 改寫了歷史,一般的 push 會被擋
gh pr merge --squash --delete-branch
不想用 rebase 也行:第四步換成 git merge main,最後一步就不用強推,普通的 git push 就好。代價是歷史上會多一個合併節點,線圖沒那麼直。

換成 --merge 或 --rebase 有用嗎?

🙅
一樣會被擋

GitHub 判斷「能不能合併」,是拿你的分支跟 main 做標準比對, 跟你打算用哪種方式合併完全無關。
所以這不是 squash 的問題,換哪一個都一樣。

可是我送 PR 的時候明明還好好的

對,衝突多半不是你造成的,是等待期間長出來的

週一 10:00
你從 main 開了一條分支,改了 README 第 3 行。 那一刻的 main 是乾淨的起點。
週一 14:00
你送出 PR,GitHub 顯示綠色的「可以合併」。 這個判斷只代表「現在」可以。
週二 09:00
隊友的 PR 先合併了,他也動了 README 第 3 行。 元凶就在這裡。main 已經不是你當初那個 main 了。
週二 11:00
你跑 gh pr merge,被退回來。 同一行有兩個版本,GitHub 不敢替你選。
所以這不是你做錯什麼。PR 開越久、越容易撞到——這也是大家鼓勵「小而快的 PR」的原因之一。

想再深入一點