stack

Stack

使用本地 stack CLI 修复可安全压缩合并的堆叠变更。它专为以下仓库设计：变更（GitHub PR 或 GitLab MR）通过 squash 合并，且合并后的分支会被删除，因此仅凭 Git 祖先关系无法保留堆叠意图。

Setup

支持通过 gh 使用 GitHub，以及通过 glab 使用 GitLab。运行 stack 前，请安装并验证对应的 CLI。

• 根据 origin 自动检测 github.com 和 gitlab.com。
• 企业主机：git config stack.codeHost github|gitlab（或通过 STACK_CODE_HOST 环境变量覆盖）。
• 自定义主干分支：git config stack.trunks dev,develop,main,master。
• 从堆叠区块中移除归属链接：git config stack.blockLink false。

日常编辑和提交仍使用普通的 git。仅在处理堆叠意图、检查、同步、合并和撤销时使用 stack。

Mental Model

dev
└─ stack-a  #101
   └─ stack-b  #102
      └─ stack-c  #103

堆叠意图会以堆叠链接的形式保存在 .git/stack/state.json 中（分支、父分支、合并基准锚点、变更编号）。会修改状态的工作流会写入 .git/stack/undo.json，以便 stack undo --apply 恢复先前状态。不要手动编辑这些文件——运行 stack sync 进行预览，运行 stack sync --apply 进行修复。

Happy Path

创建 PR 时使用正确的目标分支，让堆叠结构能够自我描述：

gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync              # preview inferred links and repairs
stack sync --apply      # record links, repair, retarget, refresh stack blocks

这是常见的工作循环。stack sync 用于预览；stack sync --apply 用于执行操作。父分支有任何变更，或 squash 合并完成后，都要重复此流程。

同步还会在修复后代分支前，先发布本地领先的父分支。对于无需本地修复的父分支，它会检查实际推送目标，并且只使用显式租约发布快进变更。重试前，请先获取并协调已分叉或未知的远程分支头。撤销会恢复仅发布到远程的变更，但不会回滚本地父分支上原本已有的提交；若远程存在意外变更，则会拒绝覆盖。

Commands

• stack status — 显示当前堆叠图（隐藏备份；代码托管平台可用时，包含未关闭变更的标题）。
• stack skill — 输出此技能，供 AI Agent 发现。
• stack doctor — 检查 Git、代码托管平台访问权限、堆叠元数据、主干分支和撤销日志的健康状况，不会修改任何内容。
• stack track <branch> --onto <parent> — 仅当目标分支未体现堆叠关系时，手动记录堆叠意图。
• stack sync [branch] — 预览推断出的链接和修复操作（不修改内容）。未指定分支时，范围限定为当前堆叠。
• stack sync --apply [branch] — 推断链接、移除过时链接、修复后代分支、调整变更目标、刷新堆叠区块，并显示树形摘要。
• stack sync --apply --keep-going — 分别处理互不相关的堆叠，报告成功和失败；只要有任何失败，就以非零状态退出。
• stack merge [branch] — 试运行根分支合并及后代修复。从当前分支推断根分支。
• stack merge --apply — 调整子变更的目标分支，squash 合并根分支，并修复后代分支。
• stack merge --auto — 调整子变更的目标分支，启用代码托管平台自动合并，等待合并完成，然后修复后代分支。
• stack merge --auto --through <branch-or-change> — 每次合并一个根分支，重复此操作，直到目标变更完成合并。
• stack history — 显示最近一次已应用的修复日志。
• stack undo — 试运行恢复上一次已应用的修改。
• stack undo --apply — 恢复分支头、变更目标和堆叠元数据。

Stack Blocks

stack sync --apply 和 stack merge --apply/--auto 会在每个未关闭变更的描述中刷新一个确定性区块：

### [Stack](https://github.com/kitlangton/stack)

1. #101
2. #102
3. **#103** 👈 current

较早的条目表示已合并的历史记录。当前变更会以粗体显示，并标注 👈 current。GitHub 使用 #123；GitLab 使用 !123 - Title。

安全规则

• 裸运行 stack sync 不会修改分支、变更或堆栈元数据。
• 默认情况下，stack merge 以试运行模式运行。
• 修改状态的命令需要 --apply（merge --auto 除外；它会等待代码托管平台，并在根分支合并后进行修复）。
• 切勿修改主干分支（dev、main、master 或任何已配置的主干分支）。
• 变基前，工具会创建一个本地备份分支。
• 正在修复或清理的分支可以由干净的同级工作树持有；如果持有分支的同级工作树存在未提交的更改，工具会在修改前失败。
• 如果重放失败，工具会中止 cherry-pick、恢复原始分支、保留备份和撤销日志，并告知你需要修复哪个分支，然后再运行 stack sync --apply。
• 如果输出不明确，请先通过 stack status、stack history 或命令帮助进行检查，再应用变更。