git-rebase - 將提交重新應用到另一個基礎之上

如果指定了 <branch>，則 git rebase 會在執行任何其他操作之前自動執行 git switch <branch>。否則，它會停留在當前分支上。

如果未指定 <upstream>，則會使用 branch.<name>.remote 和 branch.<name>.merge 選項中配置的上游分支（詳見 git-config[1]），並假定使用 --fork-point 選項。如果您當前不在任何分支上，或者當前分支沒有配置上游分支，則變基操作將中止。

當前分支中由提交引入但不在 <upstream> 中的所有更改都會儲存到一個臨時區域。這與 git log <upstream>..HEAD 顯示的提交集相同；如果 --fork-point 處於活動狀態（詳見下方 --fork-point 的說明），則與 git log fork_point'..HEAD 顯示的提交集相同；如果指定了 --root 選項，則與 git log HEAD 顯示的提交集相同。

如果提供了 --onto 選項，則當前分支將重置為 <upstream> 或 <newbase>。這與 git reset --hard <upstream>（或 <newbase>）具有完全相同的效果。ORIG_HEAD 將指向重置前分支的頂端。

之前儲存到臨時區域的提交將逐個按順序重新應用到當前分支。請注意，HEAD 中引入與 HEAD..<upstream> 中提交相同文字更改的任何提交都將被省略（即，一個上游已經接受但提交資訊或時間戳不同的補丁將被跳過）。

合併失敗可能會阻止此過程完全自動化。您將不得不解決任何此類合併失敗並執行 git rebase --continue。另一個選項是使用 git rebase --skip 繞過導致合併失敗的提交。要檢出原始的 <branch> 並移除 .git/rebase-apply 工作檔案，請改用命令 git rebase --abort。

假設存在以下歷史，並且當前分支是 "topic"

從這一點開始，以下任一命令的結果將是

會是

注意： 後者只是 git checkout topic 後面跟著 git rebase master 的簡寫。當變基操作退出時，topic 將保持為已檢出分支。

如果上游分支已包含您所做的更改（例如，因為您傳送的補丁已應用於上游），則該提交將被跳過併發出警告（如果使用 merge 後端）。例如，在以下歷史記錄上執行 git rebase master（其中 A' 和 A 引入了相同的更改集，但具有不同的提交者資訊）

將導致

這是您如何將一個基於某個分支的主題分支移植到另一個分支，以假裝您是從後者分支派生該主題分支的方法，使用 rebase --onto。

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

我們想讓 topic 從 master 分支派生；例如，因為 topic 所依賴的功能已合併到更穩定的 master 分支中。我們希望我們的樹看起來像這樣

我們可以使用以下命令實現此目的

--onto 選項的另一個示例是變基分支的一部分。如果出現以下情況

那麼命令

將導致

這在 topicB 不依賴於 topicA 的情況下很有用。

還可以透過 rebase 刪除一系列提交。如果出現以下情況

那麼命令

將導致刪除提交 F 和 G

如果 F 和 G 在某種程度上有缺陷，或者不應該成為 topicA 的一部分，這會很有用。請注意，--onto 的引數和 <upstream> 引數可以是任何有效的 commit-ish。

如果發生衝突，git rebase 將在第一個有問題​​的提交處停止，並在樹中留下衝突標記。您可以使用 git diff 定位標記（<<<<<<）並進行編輯以解決衝突。對於您編輯的每個檔案，您需要告訴 Git 衝突已解決，這通常透過以下方式完成

手動解決衝突並使用所需的解決方案更新索引後，您可以使用以下命令繼續變基過程

或者，您可以使用以下命令撤消 git rebase 操作

本節中的選項不能與其他任何選項一起使用，包括彼此之間也不能一起使用

以下選項

與以下選項不相容

此外，以下選項對不相容

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 在應用該提交後停止，以便您可以編輯檔案和/或提交訊息，修改提交，然後繼續變基。

要中斷變基（就像 "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（預設通常是 /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 中時，比如為了解決與 DownloadButton 類在 master 中引入的更改所導致的合併衝突。

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

與常規互動式變基不同，除了 pick 命令外，還有 label、reset 和 merge 命令。

label 命令在執行時將一個標籤與當前的 HEAD 關聯起來。這些標籤被建立為工作區本地引用 (refs/rewritten/<label>)，它們將在變基完成後被刪除。這樣，連結到同一倉庫的多個工作區中的變基操作不會相互干擾。如果 label 命令失敗，它會立即重新排程，並顯示一條有用的訊息，指導如何繼續。

reset 命令將 HEAD、索引和工作區重置到指定的版本。它類似於執行 exec git reset --hard <label>，但拒絕覆蓋未跟蹤的檔案。如果 reset 命令失敗，它會立即重新排程，並顯示一條有用的訊息，指導如何編輯待辦列表（這通常發生在手動將 reset 命令插入待辦列表幷包含拼寫錯誤時）。

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

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

預設情況下，merge 命令將對常規合併使用 ort 合併策略，對章魚式合併使用 octopus 策略。可以透過在呼叫變基時使用 --strategy 引數為所有合併指定預設策略，或者透過使用 exec 命令顯式呼叫帶 --strategy 引數的 git merge 來覆蓋互動式命令列表中的特定合併。請注意，當像這樣顯式呼叫 git merge 時，你可以利用標籤是工作區本地引用（例如，引用 refs/rewritten/onto 將對應於標籤 onto）這一事實，以便引用你想要合併的分支。

注意：第一個命令 (label onto) 標記了提交變基到的版本；名稱 onto 只是一個約定，是為了向 --onto 選項致敬。

還可以透過新增形式為 merge <merge-head> 的命令來從頭引入全新的合併提交。這種形式將生成一個臨時提交訊息，並始終開啟編輯器供使用者編輯。這在例如一個主題分支解決了不止一個問題並希望拆分為兩個或更多主題分支時會很有用。考慮這個待辦列表：

此列表中與 CMake 無關的那次提交很可能是為了修復切換到 CMake 所引入的所有錯誤而進行的，但它解決了不同的問題。要將此分支拆分為兩個主題分支，可以像這樣編輯待辦列表：

本節中以下所有內容均從 git-config[1] 文件中選擇性地包含。內容與彼處相同：

Git[1] 套件的一部分