《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 中签出的分支。