using-git-spice

使用 git-spice

概述

git-spice（gs）是一款用于管理堆叠式 Git 分支及其变更请求的命令行工具。

核心原则：git-spice 会跟踪分支关系（堆栈），并自动变基和提交依赖分支。

核心概念

堆栈术语：

• 堆栈：与当前分支相连的所有分支（包括上游和下游）
• 上游：基于当前分支构建的分支（子分支及其后代）
• 下游：从当前分支向下直到主干的分支（父分支及其祖先）
• 主干：主要集成分支（通常为 main 或 master）

堆栈示例：

┌── feature-c     ← upstack from feature-b
├── feature-b     ← upstack from feature-a, downstack from feature-c
├── feature-a     ← downstack from feature-b
main (trunk)

当前位于 feature-b 时：

• 上游：feature-c
• 下游：feature-a、main
• 堆栈：feature-a、feature-b、feature-c

快速参考

任务	命令	说明
初始化仓库	gs repo init	每个仓库只需执行一次。设置主干分支。
创建堆叠分支	gs branch create <name>	在当前分支之上创建分支。可使用简写 gs bc。
查看堆栈	gs log short	显示当前堆栈。使用 gs ls 或 gs log long（gs ll）查看详情。
将堆栈提交为 PR	gs stack submit	提交整个堆栈。可使用简写 gs ss。
仅提交上游	gs upstack submit	当前分支及其子分支。可使用简写 gs us s。
仅提交下游	gs downstack submit	当前分支及其父分支，直到主干。可使用简写 gs ds s。
变基整个堆栈	gs repo restack	将所有受跟踪的分支变基到各自的基分支上。
变基当前堆栈	gs stack restack	变基当前分支的堆栈。可使用简写 gs sr。
变基上游	gs upstack restack	当前分支及其子分支。可使用简写 gs us r。
将分支移到新的基分支上	gs upstack onto <base>	将当前分支及其上游移到新的基分支上。
与远程同步	gs repo sync	拉取最新内容并删除已合并的分支。
跟踪现有分支	gs branch track [branch]	将分支添加到 git-spice 跟踪中。
删除分支	gs branch delete [branch]	删除分支并对其子分支重新变基。可使用简写 gs bd。

**命令快捷方式：**大多数命令都有简写别名。使用 gs --help 查看所有别名。

常见工作流

这些工作流适用于单仓库场景。有关跨多个仓库的功能，请参阅下方的多仓库工作流。

工作流 1：创建并提交堆栈

# One-time setup
gs repo init
# Prompt asks for trunk branch (usually 'main')

# Create stacked branches
gs branch create feature-a
# Make changes, commit with git
git add . && git commit -m "Implement A"

gs branch create feature-b  # Stacks on feature-a
# Make changes, commit
git add . && git commit -m "Implement B"

gs branch create feature-c  # Stacks on feature-b
# Make changes, commit
git add . && git commit -m "Implement C"

# View the stack
gs log short

# Submit entire stack as PRs
gs stack submit
# Creates/updates PRs for all branches in stack

工作流 2：评审后更新分支

# You have feature-a → feature-b → feature-c
# Reviewer requested changes on feature-b

git checkout feature-b
# Make changes, commit
git add . && git commit -m "Address review feedback"

# Rebase upstack (feature-c) on updated feature-b
gs upstack restack

# Submit changes to update PRs
gs upstack submit
# Note: restack only rebases locally, submit pushes and updates PRs

**重要：不要手动对 feature-c 进行变基！**使用 gs upstack restack 来维护堆栈关系。

工作流 3：上游合并后同步

# feature-a was merged to main
# Need to update feature-b and feature-c

# Sync with remote (pulls main, deletes merged branches)
gs repo sync

# Restack everything on new main
gs repo restack

# Verify stack looks correct
gs log short

# Push updated branches
gs stack submit

**重要：不要将 feature-c 变基到 main 上！**feature-a 合并后：

• feature-b 变基到 main（它的新基分支）
• feature-c 变基到 feature-b（保持依赖关系）

何时使用 Git，何时使用 git-spice

使用 git-spice 来：

• 在堆栈中创建分支：gs branch create
• 对堆栈进行变基：gs upstack restack、gs repo restack
• 提交 PR：gs stack submit、gs upstack submit
• 查看堆栈结构：gs log short
• 删除分支：gs branch delete（会对其子分支重新变基）

使用 git 来：

• 修改内容：git add、git commit
• 检查状态：git status、git diff
• 查看提交历史：git log
• 执行单个分支操作：git checkout、git switch

切勿直接对堆叠分支使用 git rebase——请使用 git-spice 的 restack 命令来维护分支关系。

常见错误

错误	错误原因	正确做法
父分支合并后，将子分支变基到 trunk	破坏堆栈关系并产生冲突	使用 gs repo sync && gs repo restack
更改后使用 git push --force	绕过 git-spice 跟踪	使用 gs upstack submit 或 gs stack submit
使用 git rebase 手动变基	git-spice 不会跟踪此次变基	使用 gs upstack restack 或 gs stack restack
在错误的分支上运行 gs stack submit	可能会提交非预期分支	先检查 gs log short，查看堆栈中的内容
忘记运行 gs repo init	命令会报出不明确的错误	每个代码库运行一次 gs repo init
想用 upstack 时却用了 stack	也会提交下游分支（父分支）	使用 upstack，只提交当前分支及其子分支
以为 restack 会自动运行	提交更改后，堆栈可能会偏离	更改后显式运行 gs upstack restack

危险信号——请查阅文档

• 不清楚 stack、upstack 和 downstack 的范围
• 准备对受跟踪的分支运行 git rebase
• 不确定该使用哪个提交命令
• 遇到“not tracked”错误

不确定时，运行 gs <command> --help 查看详细用法。

身份验证和设置

首次设置：

# Authenticate with GitHub/GitLab
gs auth login
# Follow prompts for OAuth or token auth

# Initialize repository
gs repo init
# Sets trunk branch and remote

# Verify setup
gs auth status

处理冲突

如果 gs upstack restack 或 gs repo restack 遇到冲突：

1. 使用标准 Git 工作流解决冲突（git status、编辑文件、git add）
2. 使用 git rebase --continue 继续
3. git-spice 将继续对剩余分支进行变基堆栈操作
4. 解决后，运行 gs upstack submit 推送更改

如果需要中止堆栈变基操作，请查看 gs --help 了解恢复选项。

多代码库工作流

按代码库堆叠的限制

Git-spice 一次只能操作一个代码库。在跨多个代码库的精彩功能中：

• 每个代码库都有各自独立的堆栈
• 无法创建跨代码库的线性堆栈
• 分支始终位于各自所属的代码库中

多代码库 PR 提交

对于跨多个代码库的功能，请按阶段顺序提交 PR：

按阶段顺序提交：

# Phase 1 repos first (foundation)
cd shared-lib
gs stack submit
cd ..

# Phase 2 repos second
cd backend
gs stack submit
cd ..

# Phase 3 repos last (depends on earlier phases)
cd frontend
gs stack submit
cd ..

按阶段顺序提交的重要性：

• 阶段 1 的更改（例如，共享类型）必须先于阶段 2 的使用方合并
• 避免因缺少依赖项而导致构建失败
• 与开发期间的执行顺序一致

多代码库堆栈可视化

查看所有代码库中的堆栈：

# From workspace root
for repo in backend frontend shared-lib; do
  echo "=== $repo ==="
  cd $repo && gs log short && cd ..
done

多代码库同步

PR 合并后，同步所有代码库：

# From workspace root
for repo in backend frontend shared-lib; do
  echo "Syncing $repo..."
  cd $repo && gs repo sync && cd ..
done

协调跨代码库依赖关系

如果代码库 A 中的 PR 依赖于代码库 B 中的 PR：

1. 先合并代码库 B 的 PR
2. 更新代码库 A，以使用已合并的更改
3. 然后合并代码库 A 的 PR

示例：

shared-lib: PR for new types
  ↓ (merge first)
backend: PR using new types
  ↓ (merge second)
frontend: PR using backend API
  ↓ (merge third)

其他资源

• 完整 CLI 参考：gs --help
• 特定命令的帮助：gs <command> --help
• 配置：gs config --help
• 官方文档：https://abhinav.github.io/git-spice/