git-spice 是一款用于管理Git 堆叠分支（stacked Git branches）的命令行工具，支持分支栈的创建、导航、rebase 以及向 GitHub、GitLab、Bitbucket、Gitea、Forgejo 等提交 Pull/Merge Request。本文是一份 git-spice 报错排查清单：覆盖新手最常遇到的 10 个典型错误，每个都给出原因定位与最快修复方法，帮你快速恢复工作流。

📋 报错速查表

1️⃣fatal: Cannot rebase onto multiple branches.

这是gs repo sync间歇性失败时的经典报错。原因通常是有后台 Git 进程在并发 fetch，比如：

• Pure (Zsh) 提示符自动拉取：在~/.zshrc中加export PURE_GIT_PULL=0
• VS Code 自动同步：在settings.json中设置"git.autofetch": false

👉 官方说明见 Troubleshooting 指南。

2️⃣no forge found for <remote-url>

git-spice 需要根据 remote URL 推断托管服务（Forge）。当 remote 地址无法识别、且处于非交互模式时，就会报这个错。解决方法：

gs stack submit --forge github gs auth login --forge gitlab

在从已知服务 clone 下来的仓库中直接运行gs auth login，可以跳过服务选择提示。相关逻辑位于 auth.go，认证配置文档在 Authentication。

3️⃣branch not tracked: <name>

git-spice 依赖本地 ref 记录分支的 base/upstream 状态。若分支不是通过gs branch create创建的（例如手动git checkout -b或 checkout 了未跟踪分支），很多命令会报branch not tracked。

gs branch track # 跟踪当前分支 gs downstack track # 批量跟踪当前分支之下所有未跟踪分支

4️⃣branch already exists: <name>

gs branch create目标分支已存在时抛出该错误（见 branch_create.go）。解决方式：

• 换一个新分支名
• 或先gs branch delete/git branch -d删除旧分支
• 想基于其他分支创建时，可用--target指定目标分支

5️⃣not in a Git repository

所有gs命令都必须在 Git 仓库（工作树）内执行。常见原因：终端还停在仓库外的目录、或在 worktree 之外操作。确认git status可正常输出后再运行 git-spice 命令即可。

6️⃣ 认证失败：401、token 过期或权限不足

症状：gs stack submit、gs repo sync推送/拉取时报 401 /unauthorized/invalid token。

排查步骤：

gs auth status # 查看当前登录状态 gs auth logout # 清除失效凭据 gs auth login # 重新登录（可选 OAuth、Personal Access Token、环境变量等）

注意检查 token 的scopes是否覆盖所需仓库权限；环境变量注入的 token 有时缺少必要 scope，建议改用 OAuth 或刷新 PAT。

7️⃣ restack / rebase 冲突

gs stack restack本质是对栈内分支逐层 rebase，冲突时 git-spice 会停下来让你处理：

# 手动解决冲突、git add 之后： gs rebase continue # 放弃本次 restack，回到起点： gs rebase abort

💡 技巧：冲突多发生在 downstack（下层分支）改动波及上层时。可以先只 restack 单个分支（gs branch restack）缩小排查范围，命令实现见 branch_restack.go。

8️⃣ submit 失败：base 分支已过期（stale base）

当主干或下层分支已被合入新提交，而本地栈还停留在旧历史时，submit 会提示需要 restack。尤其squash merge 后：PR 被压成单个新 hash 的提交，上层分支仍指向旧历史，必须重新 restack（原理见 Limitations）。

标准修复流程：

gs repo sync --restack # 同步远端、清理已合并分支并 restack gs stack submit # 再提交整个栈

9️⃣ Fork 模式下，只有主干分支创建了 PR

当 upstream 与 push remote 不同（你没有上游仓库写权限）时，git-spice 进入Fork 模式：分支都会推送，但只会为直接基于 trunk 的分支创建 Change Request，堆在别的分支之上的分支会被跳过。

解决方案：

• 获得上游仓库推送权限后重新提交
• 注意：GitHub App 认证与 Fork 模式不兼容，需换用其他 GitHub 认证方式

🔟--label/--assign参数不生效（平台限制）

在 Bitbucket Cloud / Data Center 上，PR 不支持 labels 和 assignees，因此--label、--assign会被静默忽略；Azure DevOps 上无 assignee 字段，--assign同样无效。这不是 git-spice 故障，而是平台能力限制（详见 limits 文档）。

🧭 通用排查顺序

1. 看警告：branch not tracked等 warning 通常会直接给出建议命令
2. 保持栈新鲜：多数提交类故障的根源是本地落后于远端，先gs repo sync
3. 认证兜底：任何网络相关报错，先gs auth status→gs auth login
4. 善用短命令：熟悉 CLI shorthands 可让排查更快，如gs rs=gs repo sync、gs ss=gs stack submit

如果以上 10 种情况都没覆盖到你的报错，可优先查阅仓库内的 Troubleshooting、User Guide 与 Command Reference，它们覆盖了各平台支持与全部命令的官方说明。