Back to Details

gitbutler-stacks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitButler Stacks

GitButler 栈

Dependent branches → anchor-based stacking → reviewable chunks.
<when_to_use>
  • Sequential dependencies (e.g., refactor → API → frontend)
  • Large features broken into reviewable chunks
  • Granular code review (approve/merge early phases independently)
  • Post-hoc stack organization after exploratory coding
NOT for: independent parallel features (use virtual branches), projects using Graphite stacking
</when_to_use>
依赖分支 → 基于锚点的堆叠 → 可评审的代码块。
<when_to_use>
  • 顺序依赖（例如：重构 → API → 前端）
  • 大型功能拆分为可评审的小块
  • 精细化代码评审（可独立批准/合并早期阶段）
  • 探索性编码后进行事后栈组织
不适用场景：独立并行功能（使用虚拟分支）、使用Graphite堆叠的项目
</when_to_use>

Stacked vs Virtual Branches

堆叠分支 vs 虚拟分支

TypeUse CaseDependencies
VirtualIndependent, unrelated workNone — parallel
StackedSequential dependenciesEach builds on parent
Stacked branches = virtual branches split into dependent sequence. Default: Virtual branches are stacks of one.
类型使用场景依赖关系
虚拟分支独立、不相关的工作无 — 并行
堆叠分支顺序依赖每个分支基于父分支构建
堆叠分支 = 拆分为依赖序列的虚拟分支。 默认：虚拟分支是单个分支的栈。

Creating Stacks

创建栈

bash
undefined
bash
undefined

Base branch (no anchor)

基础分支（无锚点）

but branch new base-feature
but branch new base-feature

Stacked branch (--anchor specifies parent)

堆叠分支（--anchor 指定父分支）

but branch new child-feature --anchor base-feature
but branch new child-feature --anchor base-feature

Third level

第三层分支

but branch new grandchild-feature --anchor child-feature

**Result:** `base-feature` ← `child-feature` ← `grandchild-feature`

**Short form:** `-a` instead of `--anchor`

```bash
but branch new child -a parent
but branch new grandchild-feature --anchor child-feature

**结果：** `base-feature` ← `child-feature` ← `grandchild-feature`

**简写形式：** 使用 `-a` 代替 `--anchor`

```bash
but branch new child -a parent

Stack Patterns

栈模式

Common patterns: feature dependency chains, refactoring sequences, deep stacks.
Example - Feature Dependency:
bash
but branch new auth-core
but branch new auth-oauth --anchor auth-core
but branch new auth-social --anchor auth-oauth
See 
references/patterns.md
for detailed patterns with commit examples.
常见模式：功能依赖链、重构序列、深层栈。
示例 - 功能依赖：
bash
but branch new auth-core
but branch new auth-oauth --anchor auth-core
but branch new auth-social --anchor auth-oauth
查看 
references/patterns.md
获取包含提交示例的详细模式。

Post-Hoc Stack Organization

事后栈组织

Convert independent branches into a stack by recreating with correct anchors:
  1. Create new branch with 
    --anchor
    pointing to intended parent
  2. Move commits with 
    but rub <sha> <new-branch>
  3. Delete original branch
See 
references/reorganization.md
for detailed workflows.
通过使用正确的锚点重新创建分支，将独立分支转换为栈：
  1. 使用 
    --anchor
    指定目标父分支创建新分支
  2. 使用 
    but rub <sha> <new-branch>
    移动提交
  3. 删除原始分支
查看 
references/reorganization.md
获取详细工作流。

Publishing Stacks

发布栈

Using CLI (Preferred)

使用CLI（推荐）

bash
undefined
bash
undefined

Push and create PR for a branch

推送分支并创建PR

but push dependent-feature but pr new dependent-feature
but push dependent-feature but pr new dependent-feature

Push all unpushed branches

推送所有未推送的分支

but push

`but push` + `but pr new` handles:
- Pushing branches to remote
- Creating PRs with correct base branches
- Updating existing PRs if already created
but push

`but push` + `but pr new` 可处理：
- 将分支推送到远程仓库
- 创建带有正确基础分支的PR
- 若已创建PR则更新现有PR

Using GitHub CLI (Alternative)

使用GitHub CLI（替代方案）

bash
undefined
bash
undefined

Push branches

推送分支

git push -u origin base-feature git push -u origin dependent-feature
git push -u origin base-feature git push -u origin dependent-feature

Create PRs with correct base branches

创建带有正确基础分支的PR

gh pr create --base main --head base-feature
--title "feat: base feature"
--body "First in stack"
gh pr create --base base-feature --head dependent-feature
--title "feat: dependent feature"
--body "Depends on base-feature PR"
undefined
gh pr create --base main --head base-feature
--title "feat: base feature"
--body "First in stack"
gh pr create --base base-feature --head dependent-feature
--title "feat: dependent feature"
--body "Depends on base-feature PR"
undefined

GitHub Settings

GitHub设置

  • Enable automatic branch deletion after merge
  • Use Merge strategy (recommended) — no force pushes needed
  • Merge bottom-to-top (sequential order)
  • 启用合并后自动删除分支
  • 使用合并策略（推荐）—— 无需强制推送
  • 从下到上合并（顺序合并）

Conflict Handling in Stacks

栈中的冲突处理

GitButler resolves conflicts per-commit during rebase:
  1. When base branch updates, dependent commits rebase automatically
  2. Conflicted commits marked but don't block other commits
  3. Resolve conflicts per affected commit
  4. Partial resolution can be saved and continued later
bash
undefined
GitButler在变基期间按提交解决冲突：
  1. 当基础分支更新时，依赖提交会自动变基
  2. 冲突提交会被标记，但不会阻塞其他提交
  3. 针对受影响的提交解决冲突
  4. 部分解决结果可保存并稍后继续
bash
undefined

Update base (may trigger rebases in stack)

更新基础分支（可能触发栈中的变基）

but pull
but pull

Check which commits have conflicts

检查哪些提交存在冲突

but status
but status

Resolve in editor, GitButler auto-detects resolution

在编辑器中解决冲突，GitButler会自动检测解决结果


**Unlike git rebase:** Remaining commits continue rebasing even if some conflict.

**与git rebase不同：** 即使部分提交存在冲突，剩余提交仍会继续变基。

Stack Reorganization

栈重组

Key operations for restructuring stacks:
OperationCommand
Squash commits
but squash <branch>
or 
but rub <newer> <older>
Move commit
but rub <sha> <target-branch>
Split branchCreate anchored branch, move commits
See 
references/reorganization.md
for detailed examples.
重组栈的关键操作：
操作命令
合并提交
but squash <branch>
或 
but rub <newer> <older>
移动提交
but rub <sha> <target-branch>
拆分分支创建带锚点的分支，移动提交
查看 
references/reorganization.md
获取详细示例。

Stack Navigation

栈导航

Note: Virtual branches don't need checkout — all branches active simultaneously.
bash
undefined
注意： 虚拟分支无需切换——所有分支同时处于活跃状态。
bash
undefined

View full stack structure

查看完整栈结构

but status
but status

Work on any branch directly (no checkout needed)

直接在任意分支上工作（无需切换）

but commit base-feature -m "update base" but commit dependent-feature -m "update dependent"
but commit base-feature -m "update base" but commit dependent-feature -m "update dependent"

Inspect a specific branch

检查特定分支

but show dependent-feature
but show dependent-feature

JSON for programmatic analysis

用于程序化分析的JSON格式

but show dependent-feature --json | jq '.commits[] | .id'

<rules>

ALWAYS:
- Create stacks with `--anchor` from the start
- Merge stacks bottom-to-top (base first, dependents after)
- Snapshot before reorganizing: `but oplog snapshot --message "Before stack reorganization"`
- Keep each level small (100-250 LOC) for reviewability
- Delete empty branches after reorganization

NEVER:
- Skip stack levels when merging
- Stack independent, unrelated features (use virtual branches)
- Create deep stacks (5+ levels) without good reason
- Forget anchor when creating dependent branches

</rules>
but show dependent-feature --json | jq '.commits[] | .id'

<rules>

必须遵守：
- 从一开始就使用 `--anchor` 创建栈
- 从下到上合并栈（先合并基础分支，再合并依赖分支）
- 重组前创建快照：`but oplog snapshot --message "Before stack reorganization"`
- 保持每个层级的代码量较小（100-250行代码）以便评审
- 重组后删除空分支

禁止：
- 合并时跳过栈层级
- 堆叠独立、不相关的功能（使用虚拟分支）
- 无正当理由创建深层栈（5层以上）
- 创建依赖分支时忘记指定锚点

</rules>

Troubleshooting

故障排除

SymptomCauseSolution
Stack not showing in 
but status
Missing 
--anchor
Recreate with correct anchor
Commits in wrong stack levelWrong branch targeted
but rub <sha> correct-branch
Can't merge middle of stackWrong orderMerge bottom-to-top only
症状原因解决方案
but status
中未显示栈		缺少 
--anchor
使用正确的锚点重新创建分支
提交位于错误的栈层级目标分支错误
but rub <sha> correct-branch
无法合并栈中间的分支合并顺序错误仅从下到上合并

Recovery

恢复

To fix a branch with wrong/missing anchor: create new branch with correct anchor, move commits with 
but rub
, delete original.
See 
references/reorganization.md
for complete recovery procedures.
要修复锚点错误/缺失的分支：创建带有正确锚点的新分支，使用 
but rub
移动提交，删除原始分支。
查看 
references/reorganization.md
获取完整恢复流程。

Best Practices

最佳实践

Planning

规划

  • Start simple: 2-3 levels max initially
  • Single responsibility per level
  • Only stack when there's a real dependency
  • 从简单开始：最初最多2-3层
  • 每个层级单一职责
  • 仅当存在真实依赖时才使用堆叠

Maintenance

维护

  • Run 
    but status
    regularly to verify structure
  • Commit to correct branches immediately
  • Clean up empty branches
  • 定期运行 
    but status
    验证结构
  • 立即提交到正确的分支
  • 清理空分支

Communication

沟通

  • Clear commit messages explaining why stack level exists
  • Descriptive names indicating stack relationship
  • Share 
    but status
    when coordinating
<references>
  • 清晰的提交消息，解释栈层级存在的原因
  • 描述性的分支名称，表明栈关系
  • 协作时分享 
    but status
    结果
<references>

Reference Files

参考文件

  • references/patterns.md
     — Detailed stack patterns (feature dependency, refactoring, deep stacks)
  • references/reorganization.md
     — Post-hoc organization, squashing, moving commits, splitting
  • references/patterns.md
     — 详细的栈模式（功能依赖、重构、深层栈）
  • references/reorganization.md
     — 事后组织、合并提交、移动提交、拆分分支

Related Skills

相关技能

  • gitbutler-virtual-branches — Core GitButler workflows
  • gitbutler-complete-branch — Merging to main
  • gitbutler-multi-agent — Multi-agent coordination
  • gitbutler-virtual-branches — GitButler核心工作流
  • gitbutler-complete-branch — 合并到主分支
  • gitbutler-multi-agent — 多Agent协作

External

外部资源

</references>
</references>