《Cursor文檔》-分支棧

什麼是分支棧？¶

分支棧是一系列彼此依賴、逐層構建的分支。

如果你的主幹分支是 main，分支棧可能如下所示：

gitGraph
  commit
  branch branch-1
  checkout branch-1
  commit
  branch branch-2
  checkout branch-2
  commit
  branch branch-3
  checkout branch-3
  commit

在上述設置中：

branch-1 基於 main
branch-2 基於 branch-1
branch-3 基於 branch-2

爲何使用 `gt` CLI 管理分支棧¶

以下情況下，gt CLI 尤其適用：

一個功能可自然拆分爲多個可評審的部分
希望審閱人看到清晰的變更序列，而不是一個巨大的 PR
較低層級的分支仍在評審時，需要繼續工作
隨着主幹推進，分支棧需要定期重新整理

創建分支¶

當某項更改可以作爲獨立分支時，使用 gt create。

修改分支¶

如需繼續在當前分支上工作，請使用 gt modify。

這可能包括：

修改現有分支
添加新的提交
更新下層分支，並重新整理其上方的分支

提交 PR¶

使用 gt submit 推送分支並創建 PR。

處理分支棧時，通常會使用：

gt submit --stack

與主幹同步¶

使用 gt sync 更新本地主幹狀態、清理已合併的工作，並重新整理仍需合入的內容。

這是命令行界面中最實用的命令之一，可避免分支棧與實際狀態偏離過遠。

在分支棧中切換¶

有了分支棧後，如何在其中切換就很重要。gt CLI 提供了感知分支棧的切換命令，無需記住每個分支的名稱。

常用命令：

gt up 切換到子分支
gt down 切換到父分支
gt top 跳轉到當前分支棧的頂層分支
gt bottom 跳轉到最接近主幹的分支
gt checkout --stack 將可選分支限定爲當前分支棧
gt log 顯示分支棧結構

主幹變動時重新整理分支棧¶

分支棧很好用，但主幹一旦發生變動，就需要維護。

使用：

gt restack — 將當前分支棧中的每個分支變基到更新後的父分支上。
gt sync — 將所有分支與遠程同步，提示刪除已合併或已關閉 PR 對應的分支，重新整理可無衝突重新整理的分支；如果無法快進，則用遠程版本覆蓋主幹。

調整分支棧¶

分支棧並不總能一次整理妥當。有時一個分支太大，有時兩個分支其實應該合併爲一個，有時順序不對。

gt CLI 也提供了相應的命令。

拆分分支¶

當需要將一個分支拆分爲多個較小的分支時，使用 gt split。

摺疊分支¶

當某個分支需要併入其父分支時，使用 gt fold。

重新排序或移動分支¶

需要調整依賴關係時，使用 gt move 或 gt reorder。

壓縮或吸收更改¶

當你想整理分支棧中的提交歷史時，可使用 gt squash 或 gt absorb。

對於明顯應歸入較早分支的暫存代碼塊，gt absorb 尤其方便。它可以將更改放入下層正確的提交中，然後重新整理其上方的分支。

刪除、pop、跟蹤和取消跟蹤¶

gt delete 會刪除已跟蹤的分支，並將其子分支重新整理到父分支上
gt pop 會刪除分支，但將其中的工作保留在工作樹中
gt track 會將現有分支納入已跟蹤分支棧的元數據
gt untrack 會取消對分支的跟蹤

Git 依然可用¶

gt CLI 並不會取代 Git。在許多場景下，它只是原樣傳遞命令。

感知分支棧的操作使用 gt
檢查和常規暫存時，繼續使用 Git 風格的命令

Worktree 與高級設置¶

gt CLI 支持 Git worktree，但這仍是一種高級工作流。如果某個分支已在另一個 worktree 中籤出，部分命令會避免修改該分支，或要求你更明確地指定操作。

如果你的團隊大量使用 worktree，可以將其視爲受支持的功能，但仍應更加謹慎地操作。

從 gt 版本 1.8.4 開始，gt 在大多數情況下不會修改已在另一個 worktree 中籤出的分支。