gitbutler-complete-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Complete GitButler Virtual Branch

完成GitButler虚拟分支

Virtual branch ready → snapshot → merge to main → cleanup → return.

<when_to_use>

Virtual branch work is complete and ready to ship
Tests pass and code is reviewed (if required)
Ready to merge changes into main branch
Need to clean up completed branches

NOT for: ongoing work, branches needing more development, stacks (complete bottom-to-top)

</when_to_use>

虚拟分支准备就绪 → 创建快照 → 合并到main分支 → 清理 → 返回工作区。

<when_to_use>

虚拟分支开发完成，准备推送上线
测试通过且代码已完成评审（如有要求）
准备将变更合并到main分支
需要清理已完成的分支

不适用场景：正在进行的开发工作、仍需继续开发的分支、堆叠分支（需自底向上完成）

</when_to_use>

TL;DR

快速上手

Using CLI (preferred):

but oplog snapshot

but push <branch>

but pr new <branch>

-> merge PR on GitHub ->

but branch delete <branch>

Direct merge:

but oplog snapshot

git checkout main

git pull

git merge --no-ff refs/gitbutler/<branch>

git push

but branch delete <branch>

git checkout gitbutler/workspace

Manual PR workflow:

git push origin refs/gitbutler/<branch>:refs/heads/<branch>

gh pr create

-> merge PR -> cleanup

See detailed workflows below.

使用CLI（推荐）：

but oplog snapshot

→

but push <branch>

→

but pr new <branch>

→ 在GitHub上合并PR →

but branch delete <branch>

直接合并：

but oplog snapshot

→

git checkout main

→

git pull

→

git merge --no-ff refs/gitbutler/<branch>

→

git push

→

but branch delete <branch>

→

git checkout gitbutler/workspace

手动PR工作流：

git push origin refs/gitbutler/<branch>:refs/heads/<branch>

→

gh pr create

→ 合并PR → 清理

详见下方详细工作流。

Pre-Integration Checklist

集成前检查清单

Run through before any integration:

Check	Command	Expected
GitButler running	`but --version`	Version output
Work committed	`but status`	Committed changes, no unassigned files
Tests passing	`bun test` (or project equivalent)	All green
Base updated	`but pull`	Up to date with main
Snapshot created	`but oplog snapshot -m "Before integrating..."`	Snapshot ID returned

在执行任何集成操作前，请完成以下检查：

检查项	命令	预期结果
GitButler是否运行	`but --version`	输出版本信息
工作内容已提交	`but status`	变更已提交，无未分配文件
测试通过	`bun test` （或项目对应测试命令）	全部测试通过
基准分支已更新	`but pull`	与main分支保持同步
已创建快照	`but oplog snapshot -m "Before integrating..."`	返回快照ID

Integration Workflows

集成工作流

A. Using CLI (Preferred)

A. 使用CLI（推荐）

bash

undefined

bash

undefined

1. Verify branch state

1. 验证分支状态

but status but show feature-auth

2. Create snapshot

2. 创建快照

but oplog snapshot --message "Before publishing feature-auth"

3. Authenticate with forge (one-time)

3. 与代码托管平台认证（仅需一次）

but config forge auth

4. Push branch and create PR

4. 推送分支并创建PR

but push feature-auth but pr new feature-auth

5. Review and merge PR on GitHub

5. 在GitHub上评审并合并PR

6. Update local and clean up

6. 更新本地仓库并清理

but pull but branch delete feature-auth


**Benefits:**
- Full CLI workflow, no GUI needed
- Correct base branch set automatically for stacks
- Stays in GitButler workspace throughout

but pull but branch delete feature-auth


**优势：**
- 全CLI工作流，无需使用GUI
- 自动为堆叠分支设置正确的基准分支
- 全程可在GitButler工作区操作

B. Direct Merge to Main

B. 直接合并到main分支

bash

undefined

bash

undefined

1. Verify branch state

1. 验证分支状态

but status but show feature-auth

2. Create snapshot

2. 创建快照

but oplog snapshot --message "Before integrating feature-auth"

3. Switch to main

3. 切换到main分支

git checkout main

4. Update main

4. 更新main分支

git pull origin main

5. Merge with --no-ff (preserves history)

5. 使用--no-ff合并（保留分支历史）

git merge --no-ff refs/gitbutler/feature-auth -m "feat: add user authentication"

6. Push

6. 推送变更

git push origin main

7. Clean up

7. 清理分支

but branch delete feature-auth git checkout gitbutler/workspace

undefined

but branch delete feature-auth git checkout gitbutler/workspace

undefined

C. Manual Pull Request Workflow

C. 手动创建PR工作流

bash

undefined

bash

undefined

1. Push branch to remote

1. 将分支推送到远程仓库

git push origin refs/gitbutler/feature-auth:refs/heads/feature-auth

2. Create PR

2. 创建PR

gh pr create --base main --head feature-auth
--title "feat: add user authentication"
--body "Description..."

3. Wait for review and approval

3. 等待评审与批准

4. Merge PR (via GitHub UI or CLI)

4. 合并PR（通过GitHub UI或CLI）

gh pr merge feature-auth --squash

5. Update main and clean up

5. 更新main分支并清理

git checkout main git pull origin main but branch delete feature-auth git checkout gitbutler/workspace

undefined

git checkout main git pull origin main but branch delete feature-auth git checkout gitbutler/workspace

undefined

D. Stacked Branches (Bottom-Up)

D. 堆叠分支（自底向上）

bash

undefined

bash

undefined

Must merge in order: base → dependent → final

必须按顺序合并：基准分支 → 依赖分支 → 最终分支

1. Merge base branch first

1. 先合并基准分支

git checkout main && git pull git merge --no-ff refs/gitbutler/feature-base -m "feat: base feature" git push origin main but branch delete feature-base git checkout gitbutler/workspace

2. Update remaining branches

2. 更新剩余分支

but pull

3. Merge next level

3. 合并下一级分支

git checkout main && git pull git merge --no-ff refs/gitbutler/feature-api -m "feat: API feature" git push origin main but branch delete feature-api git checkout gitbutler/workspace

4. Repeat for remaining stack levels

4. 对剩余堆叠层级重复上述操作


> For comprehensive stacked branch management, load the **gitbutler-stacks** skill.


> 如需全面的堆叠分支管理，请加载**gitbutler-stacks** Skill。

Error Recovery

错误恢复

Merge Conflicts

合并冲突

bash

undefined

bash

undefined

View conflicted files

查看冲突文件

git status

Resolve conflicts manually

手动解决冲突

Stage resolved files

标记已解决的文件

git add src/auth.ts

Complete merge

完成合并

git commit

Verify and push

验证并推送

git push origin main

Clean up

清理分支

but branch delete feature-auth git checkout gitbutler/workspace

undefined

but branch delete feature-auth git checkout gitbutler/workspace

undefined

Push Rejected (Main Moved Ahead)

推送被拒绝（main分支已更新）

bash

git pull origin main

bash

git pull origin main

Resolve any conflicts if main diverged

若main分支已偏离，解决冲突

git push origin main

undefined

git push origin main

undefined

Undo Integration (Not Pushed Yet)

撤销集成（尚未推送）

bash

git reset --hard HEAD~1
git checkout gitbutler/workspace

bash

git reset --hard HEAD~1
git checkout gitbutler/workspace

Undo Integration (Already Pushed)

撤销集成（已推送）

bash

git revert -m 1 HEAD
git push origin main

bash

git revert -m 1 HEAD
git push origin main

Post-Integration Cleanup

集成后清理

bash

undefined

bash

undefined

Delete integrated virtual branch

删除已集成的虚拟分支

but branch delete feature-auth

Clean up remote branch (if created for PR)

清理远程分支（若为创建PR而创建）

git push origin --delete feature-auth

Verify workspace is clean

验证工作区已清理

but status # Should show remaining active branches only but status # Branch should be gone


<rules>

ALWAYS:
- Create snapshot before integration: `but oplog snapshot --message "..."`
- Use `--no-ff` flag to preserve branch history
- Return to workspace after git operations: `git checkout gitbutler/workspace`
- Run tests before integrating
- Complete stacked branches bottom-to-top

NEVER:
- Merge without snapshot backup
- Skip updating main first (`git pull`)
- Forget to return to `gitbutler/workspace`
- Merge middle of stack before base
- Force push to main without explicit confirmation

</rules>

but status # 应仅显示剩余活跃分支 but status # 目标分支应已删除


<rules>

必须遵守：
- 集成前务必创建快照：`but oplog snapshot --message "..."`
- 使用`--no-ff`标志保留分支历史
- 执行Git操作后返回工作区：`git checkout gitbutler/workspace`
- 集成前运行测试
- 自底向上完成堆叠分支的合并

严禁：
- 未创建快照备份就执行合并
- 跳过更新main分支的步骤（`git pull`）
- 忘记返回`gitbutler/workspace`
- 在合并基准分支前合并堆叠分支的中间层
- 未明确确认就强制推送到main分支

</rules>

Troubleshooting

故障排查

Symptom	Cause	Solution
Merge conflicts	Diverged from main	Resolve conflicts, stage, commit
Push rejected	Main moved ahead	`git pull` , resolve, push
Branch not found	Wrong ref path	Use `refs/gitbutler/<name>`
Can't return to workspace	Integration branch issue	`git checkout gitbutler/workspace`

症状	原因	解决方案
合并冲突	与main分支已偏离	手动解决冲突，标记，提交
推送被拒绝	main分支已更新	`git pull` ，解决冲突后推送
分支未找到	引用路径错误	使用 `refs/gitbutler/<name>`
无法返回工作区	集成分支存在问题	执行 `git checkout gitbutler/workspace`

Emergency Recovery

紧急恢复

bash

undefined

bash

undefined

If integration went wrong

若集成操作出现问题

but oplog but undo # Restores pre-integration state

but oplog but undo # 恢复到集成前状态

If stuck after git operations

若执行Git操作后陷入异常状态

git checkout gitbutler/workspace

undefined

git checkout gitbutler/workspace

undefined

Best Practices

最佳实践

Keep branches small:

Small branches = easier merges
Aim for single responsibility per branch

Update base regularly:

bash

but pull

Test before integrating:

Always run full test suite before merging

Meaningful merge commits:

bash

undefined

保持分支粒度小：

分支越小，合并越容易
每个分支仅负责单一功能

定期更新基准分支：

bash

but pull

集成前运行测试：

合并前务必运行完整测试套件

有意义的合并提交信息：

bash

undefined

Good: Describes what and why

推荐：清晰描述变更内容与原因

git merge --no-ff feature-auth -m "feat: add JWT-based user authentication"

Bad: Generic message

不推荐：通用模糊的信息

git merge --no-ff feature-auth -m "Merge branch"


<references>

git merge --no-ff feature-auth -m "Merge branch"


<references>

Related Skills

Reference Files

参考文档

gitbutler-virtual-branches/references/reference.md — CLI reference and troubleshooting

gitbutler-virtual-branches/references/reference.md — CLI参考与故障排查

External

外部链接

GitButler GitHub Integration

</references>

GitButler GitHub Integration

</references>