stack-create

Stack Create

从多步骤计划初始化一组堆叠分支。 计划中的每个逻辑切片都会成为一个分支，并以 前一个切片的分支作为基准。

适用场景

当计划产生 2 个或更多有序变更，且每个变更都依赖于前一个变更 完成（并合并）后才能提交时，使用 stack-create。 对于互不依赖的变更，请改用并行工作树 （参见 egregore）。

不适用场景

• 单个独立变更，这种情况应正常创建分支
• 堆叠分支已存在且需要发布（使用 sanctum:stack-push）

前置条件

• Git 2.38+（运行 git version | awk '{print $3}' 检查）
• gh CLI 已完成身份验证
• 已编写包含有序切片的计划（来自 do-issue 或 attune:blueprint）
• 基准分支上的工作树干净（运行 git status）

必需的进度跟踪

开始前创建进度项：

1. stack-create:git-version-checked
2. stack-create:slices-identified
3. stack-create:branches-created
4. stack-create:stack-verified

步骤 1：验证 Git 版本（git-version-checked）

git version

确认输出为 2.38.0 或更高版本。 否则，--update-refs 标志不可用。 警告用户，并回退到手动分支跟踪。

检查是否有可选的 jj 加速器：

if command -v jj &>/dev/null && jj root &>/dev/null 2>&1; then
  echo "jj available"
else
  echo "using git --update-refs"
fi

步骤 2：识别切片（slices-identified）

阅读计划并提取有序切片。 每个切片必须满足以下条件：

• 只涉及一个逻辑事项（一项 PR 规模的变更）
• 明确依赖前一个切片（如果有）
• 名称简短，适合作为分支后缀

包含三个部分的计划的切片示例：

Slice 1: add-schema     -- database schema changes
Slice 2: add-api        -- API layer (depends on schema)
Slice 3: add-ui         -- frontend (depends on API)

创建分支前，记录切片列表。

步骤 3：创建分支（branches-created）

从基准分支（通常为 master 或 main）开始：

BASE=master
STACK=stack/my-feature

# Slice 1 branches from master
git checkout -b ${STACK}/add-schema ${BASE}

# Slice 2 branches from slice 1
git checkout -b ${STACK}/add-api ${STACK}/add-schema

# Slice 3 branches from slice 2
git checkout -b ${STACK}/add-ui ${STACK}/add-api

命名约定：stack/<feature-name>/<slice-name>

返回第一个切片分支以开始工作：

git checkout ${STACK}/add-schema

jj 加速器（如果可用）

# jj creates an empty commit on each branch automatically
# Use jj new to move to a new change
jj new -m "stack: add-schema" --no-edit

步骤 4：验证堆叠分支（stack-verified）

确认分支拓扑正确：

git log --oneline --graph \
  ${BASE}..${STACK}/add-ui

每个切片分支都应位于基准分支之上，构成一条线性链。

如果 jj 可用：

jj log --revisions \
  "ancestors(${STACK}/add-ui, 10) & !ancestors(${BASE})"

备注

• 每个切片上至少有一个提交前，切勿推送分支（空分支会导致 PR 难以理解）
• 按约定，分支中的切片名称会成为 PR 标题前缀；请保持简短且描述明确
• 创建堆叠分支后，继续执行 stack-push 以创建 PR，或逐个处理切片并在准备就绪时推送
• 如果计划发生变化，请手动添加或删除分支，并在步骤 4 重新验证拓扑

退出条件

• 所有 4 个进度项（从 stack-create:git-version-checked 到 stack-create:stack-verified）都在开始创建分支前创建，并按顺序标记为完成
• 已确认 Git 版本 ≥ 2.38.0；如果未达到，则记录回退到手动 分支跟踪的方案并警告用户
• 已按命名约定创建所有切片分支： stack/<feature-name>/<slice-name>
• git log --oneline --graph <base>..<tip> 显示一条线性链， 各切片分支按依赖顺序排列
• 验证拓扑后，工作树已返回第一个切片分支