git-rebase - 在另一個基底端點之上重新套用提交

將一系列提交移植到不同的起點。您也可以使用 git rebase 來重新排序或合併提交：請參閱下方的「互動模式」了解具體作法。

例如，假設您一直在如下歷史中的 topic 分支上工作，並且想要「追上」 master 分支的工作進度。

您想將自從與 master 分離以來在 topic 上所做的提交（即 A、B 和 C）移植到當前 master 的頂端。在檢出 topic 分支時，您可以透過執行 git rebase master 來完成此操作。如果您想在另一個分支上對 topic 進行重基，git rebase master topic 是 git checkout topic && git rebase master 的簡寫。

如果在執行過程中發生合併衝突，git rebase 會停在第一個有問題的提交並留下衝突標記。如果發生這種情況，您可以採取以下行動之一：

如果您未指定重基到的 <upstream>（上游），則會使用 branch.<name>.remote 和 branch.<name>.merge 選項中設定的上游（詳情請參閱 git-config[1]），並假設使用 --fork-point 選項。如果您目前不在任何分支上，或者當前分支沒有設定上游，則重基將中止。

這是對 git rebase <upstream> 所做操作的簡化描述：

以下說明如何使用 rebase --onto 將基於某個分支的主題分支移植到另一個分支，以假裝您是從後者分支分叉出該主題分支的。

首先假設您的 topic 是基於 next 分支的。例如，在 topic 中開發的功能依賴於 next 中的某些功能。

我們想讓 topic 從 master 分支分叉出來；例如，因為 topic 所依賴的功能已被合併到更穩定的 master 分支中。我們希望我們的結構如下所示：

我們可以使用以下命令實現：

--onto 選項的另一個例子是重基分支的一部分。如果我們有以下情況：

那麼命令：

會導致：

這在 topicB 不依賴於 topicA 時非常有用。

重基也可以移除一段範圍的提交。如果我們有以下情況：

那麼命令：

將導致移除提交 F 和 G：

如果 F 和 G 存在某種缺陷，或者不應成為 topicA 的一部分，這會很有用。請注意，--onto 的參數和 <upstream> 參數可以是任何有效的提交對象 (commit-ish)。

本節中的選項不能與任何其他選項（包括彼此）同時使用：

範例請參閱上方的「使用 --ONTO 移植主題分支」。

以下選項：

與以下選項不相容：

此外，以下成對的選項不相容：

git rebase 有兩個主要的後端：apply 和 merge。（apply 後端以前稱為 am 後端，但該名稱導致了混淆，因為它看起來像動詞而不是名詞。此外，merge 後端以前稱為互動式後端，但現在也用於非互動式情況。兩者都根據支撐各自底層功能的名稱重新命名。）這兩個後端的行為存在一些細微差別：

合併機制（git merge 和 git pull 命令）允許透過 -s 選項選擇後端 合併策略。某些策略還可以接受自己的選項，這些選項可以透過向 git merge 和/或 git pull 提供 -X<option> 參數來傳遞。

對於使用三方合併的策略（包括預設的 ort），如果在兩個分支上都做了更改，但後來在其中一個分支上還原了該更改，則合併結果中將存在該更改；有些人覺得這種行為很令人困惑。這是因為執行合併時只考慮分支頭和合併基底，而不考慮單個提交。因此，合併演算法將還原的更改視為完全沒有更改，並代之以更改後的版本。

您應該了解在共享的儲存庫上使用 git rebase 的後果。另請參閱下方的「從上游重基中恢復」。

執行重基時，如果存在 pre-rebase 掛鉤，它會首先執行。您可以使用此掛鉤進行健全性檢查，如果重基不合適，則拒絕重基。請參閱 pre-rebase 掛鉤範本指令碼以獲取範例。

完成後，<branch> 將成為當前分支。

以互動方式重基意味著您有機會編輯正在重基的提交。您可以對提交重新排序，也可以刪除提交（剔除錯誤或不需要的補丁）。

互動模式適用於此類工作流程：

其中第 2 點包含以下幾種情況：

a) 常規使用

b) 獨立修復

有時 b.2. 中修復的內容無法修改到它所修復的那個不完美的提交中，因為該提交深埋在補丁系列中。這正是互動式重基的用途：在大量 "a" 和 "b" 之後使用它，透過重新排列和編輯提交，並將多個提交壓縮為一個。

從您想要原樣保留的最後一個提交開始啟動：

系統將啟動一個編輯器，列出當前分支中給定提交之後的所有提交（忽略合併提交）。您可以隨意重新排序此列表中的提交，也可以刪除它們。列表看起來大概像這樣：

單行描述純粹是為了方便您閱讀；git rebase 不會看它們，而是看提交名稱（在此範例中為 "deadbee" 和 "fa1afe1"），因此請勿刪除或編輯名稱。

透過將 "pick" 指令替換為 "edit" 指令，您可以告訴 git rebase 在套用該提交後停止，以便您可以編輯檔案和/或提交訊息、修改 (amend) 提交並繼續重基。

要中斷重基（就像 "edit" 指令會做的那樣，但不先挑選任何提交），請使用 "break" 指令。

如果您只想編輯某個提交的提交訊息，請將 "pick" 指令替換為 "reword" 指令。

要丟棄一個提交，請將 "pick" 指令替換為 "drop"，或直接刪除該行。

如果您想將兩個或多個提交合併為一個，請將第二個及後續提交的 "pick" 指令替換為 "squash" 或 "fixup"。如果提交有不同的作者，則合併後的提交將歸功於第一個提交的作者。建議的合併提交訊息是第一個提交的訊息與 "squash" 指令標識的訊息的串接，省略 "fixup" 指令標識的提交訊息，除非使用了 "fixup -c"。在這種情況下，建議的提交訊息僅為 "fixup -c" 提交的訊息，並且會開啟編輯器允許您編輯該訊息。"fixup -c" 提交的內容（補丁）仍會併入合併後的提交中。如果有多個 "fixup -c" 提交，則使用最後一個提交的訊息。您也可以使用 "fixup -C" 來獲得與 "fixup -c" 相同的行為，但不開啟編輯器。

當 "pick" 被替換為 "edit" 或命令因合併錯誤而失敗時，git rebase 將停止。完成編輯和/或解決衝突後，您可以使用 git rebase --continue 繼續。

例如，如果您想對最後 5 個提交重新排序，使原來的 HEAD~4 成為新的 HEAD。為了實現這一點，您可以這樣呼叫 git rebase：

然後將第一個補丁移至列表末尾。

您可能想要重新建立合併提交，例如如果您有這樣的歷史：

假設您想將從 "A" 開始的側支重基到 "Q"。確保當前 HEAD 為 "B"，然後呼叫：

重新排序和編輯提交通常會產生未經測試的中間步驟。您可能想透過執行測試來檢查歷史編輯是否破壞了任何東西，或者至少透過使用 "exec" 指令（簡寫為 "x"）在歷史的中間點重新編譯。您可以透過建立如下所示的待辦列表來做到這一點：

當命令失敗（即以非 0 狀態退出）時，互動式重基將停止，給您修復問題的機會。您可以使用 git rebase --continue 繼續。

"exec" 指令在 shell（預設 shell，通常是 /bin/sh）中啟動命令，因此您可以使用 shell 功能（如 "cd"、">"、";" …​）。該命令在工作區的根目錄下執行。

此指令可讓您檢查中間提交是否可編譯。待辦列表會變成這樣：

在互動模式下，您可以用 "edit" 操作標記提交。然而，這並不一定意味著 git rebase 期望這次編輯的結果恰好是一個提交。事實上，您可以撤銷該提交，或者新增其他提交。這可以用來將一個提交分割成兩個：

如果您不絕對確定中間修訂版本是一致的（它們可以編譯、通過測試套件等），您應該使用 git stash 在每次提交、測試後儲藏尚未提交的更改，並在需要修復時修改提交。

在他人已基於其開展工作之分支上進行重基（或任何其他形式的重寫）是一個壞主意：其下游的任何人都被迫手動修復其歷史記錄。本節說明如何從下游的角度進行修復。然而，真正的修復方法應該是從一開始就避免重基上游。

為了說明，假設您處於有人開發 subsystem（子系統）分支，而您正在開發依賴於此 subsystem 的 topic（主題）分支的情況。您最終可能會得到如下所示的歷史：

如果 subsystem 針對 master 進行了重基，會發生以下情況：

如果您現在照常繼續開發，並最終將 topic 合併到 subsystem，那麼來自 subsystem 的提交將永遠重複存在：

此類重複提交通常是不受歡迎的，因為它們會使歷史變得混亂，難以追蹤。為了清理歷史，您需要將 topic 上的提交移植到新的 subsystem 頂端，即重基 topic。這會產生漣漪效應：topic 下游的任何人都被迫也要重基，依此類推！

修復方法有兩種，將在以下小節中討論：

互動式重基命令最初旨在處理單個補丁系列。因此，從待辦列表中排除合併提交是有意義的，因為開發人員可能在分支上工作時合併了當時的 master，最終只是為了將所有提交重基到 master 上（跳過合併提交）。

然而，開發人員想要重新建立合併提交是有正當理由的：在處理多個相互關聯的分支時保持分支結構（或「提交拓撲」）。

在以下範例中，開發人員在一個主題分支上重構按鈕定義的方式，並在另一個主題分支上使用該重構來實作「報告錯誤」按鈕。git log --graph --format=%s -5 的輸出可能如下所示：

開發人員可能希望將這些提交重基到較新的 master，同時保留分支拓撲，例如當預計第一個主題分支比第二個更早整合到 master 時，例如為了解決與進入 master 的 DownloadButton 類別更改之間的合併衝突。

此重基可以使用 --rebase-merges 選項執行。它將產生如下所示的待辦列表：

與常規的互動式重基相比，除了 pick 指令外，還有 label、reset 和 merge 指令。

label 指令在執行時會將標籤與目前的 HEAD 關聯。這些標籤被建立為工作樹區域引用 (refs/rewritten/<label>)，並在變基（rebase）結束時刪除。如此一來，在連結到同一個儲存庫的多個工作樹中進行的變基操作就不會互相干擾。如果 label 指令失敗，它會立即重新排程，並提供如何繼續操作的實用訊息。

reset 指令會將 HEAD、索引（index）和工作樹重設為指定的修訂版本。它類似於 exec git reset --hard <label>，但拒絕覆蓋未追蹤的檔案。如果 reset 指令失敗，它會立即重新排程，並提供如何編輯待辦清單的實用訊息（這通常發生在手動將 reset 指令插入待辦清單且包含打字錯誤時）。

merge 指令會將指定的修訂版本合併到當時的 HEAD 中。使用 -C <original-commit> 時，會使用指定合併提交的提交訊息。當 -C 改為小寫的 -c 時，合併成功後會在編輯器中開啟該訊息，以便使用者編輯訊息。

如果 merge 指令因合併衝突以外的任何原因失敗（即合併操作甚至尚未開始），它會立即重新排程。

預設情況下，merge 指令對一般合併會使用 ort 合併策略，而對多路合併（octopus merges）則使用 octopus。使用者可以在呼叫 rebase 時使用 --strategy 參數為所有合併指定預設策略，或者可以在互動式指令清單中使用 exec 指令明確呼叫帶有 --strategy 參數的 git merge 來覆蓋特定的合併。請注意，當像這樣明確呼叫 git merge 時，您可以利用標籤是工作樹區域引用（例如：引用 refs/rewritten/onto 會對應到標籤 onto）這一事實，來引用您想要合併的分支。

注意：第一個指令 (label onto) 會標記提交要變基到的目標修訂版本；onto 這個名稱只是一個慣例，是為了呼應 --onto 選項。

也可以透過加入格式為 merge <merge-head> 的指令，從頭開始引入全新的合併提交。這種形式會產生一個暫定的提交訊息，並始終開啟編輯器讓使用者進行編輯。這在某些情況下很有用，例如當一個主題分支（topic branch）被發現處理了不只一個問題，並希望拆分為兩個甚至更多主題分支時。請考慮這個待辦清單

此清單中唯一與 CMake 無關的提交，很可能是因為在修復由切換到 CMake 所引入的所有錯誤時產生的動機，但它處理的是不同的問題。為了將此分支拆分為兩個主題分支，可以像這樣編輯待辦清單

本節中此行以下的內容是從 git-config[1] 文件中選擇性包含的。內容與該處找到的內容相同

git[1] 套件的一部分