rebaseplan

rebaseplan

对分支进行变基很容易开始，却很难撤销，尤其是其他人已经基于旧历史开展工作时。风险往往不会体现在分支名称中：普通变基会压平的合并提交、原始提交可能也存在于上游的 squash 合并标记、大幅领先的上游，以及改写后会被弃置的已发布历史。rebaseplan 会在你开始前读取这些情况，并返回计划，而不是让你措手不及。

你需要提供该分支自己的提交，按从旧到新的顺序排列，每个提交包含哈希、主题，以及可选的合并提交标记。你也可以提供上游分支有而该分支没有的提交，并说明该分支是否已推送或共享。工具不会获取、变基或推送任何内容——它只进行统计并提供建议。

提交只有在以下两种情况下才会被计为 squash 标记：主题以 Squashed commit 开头，或以类似 (#123) 的 GitHub squash 合并后缀结尾——固定测试使用正则表达式 /\(#\d+\)$/。无论上游提交的主题是什么，它们都不会被计为标记。

强制推送风险遵循固定表格。未发布的分支风险为 low。已发布且没有合并提交和 squash 标记的分支风险为 medium。已发布且包含其中任意一种的分支风险为 high。

推荐策略按首次匹配项确定：存在任何合并提交时，使用 rebase_with_merge_preservation；否则，存在任何 squash 标记时，使用 interactive_squash_cleanup；否则，使用 linear_rebase。因此，两者同时存在时，合并历史优先于 squash 标记。

计划的步骤始终以获取上游开始，并以在变基后的 HEAD 上运行测试套件及推送说明结束：对于已发布的分支，先创建备份分支，再使用 --force-with-lease，绝不使用普通的 --force；对于从未发布的分支，则使用普通推送。警告按顺序指出合并提交、squash 标记、上游领先至少 10 个提交（无论具体数量是多少，警告文本都固定），以及已发布历史改写。

格式错误的输入——缺失、为空或非数组的 commits，缺失、为空或类型不是字符串的 hash 或 subject，类型不是布尔值的 merge，类型错误的 upstream_commits 条目，或类型不是布尔值的 published——会导致验证错误，并指出出错路径，不返回任何部分结果。未知的额外字段会被忽略。

CLI

npx @reneturcios/rebaseplan plan --input args.json
npx @reneturcios/rebaseplan --version

args.json 包含完整的参数对象：

{
  "commits": [
    { "hash": "a1b2c3", "subject": "Add login form" },
    { "hash": "d4e5f6", "subject": "Merge branch 'main'", "merge": true }
  ],
  "upstream_commits": [
    { "hash": "f7a8b9", "subject": "Bump dependencies" }
  ],
  "published": true
}

upstream_commits 默认为 []，published 默认为 false，每个提交的 merge 默认为 false。结果以 JSON 格式输出：

{
  "commit_count": 2,
  "merge_commits": 1,
  "squash_markers": 0,
  "upstream_new_commits": 1,
  "published": true,
  "force_push_risk": "high",
  "recommended_strategy": "rebase_with_merge_preservation",
  "steps": [
    "fetch upstream before planning the final rebase",
    "create a backup branch pointing at the current head",
    "rebase onto upstream preserving merge commits",
    "run the test suite on the rebased head",
    "push with --force-with-lease, never plain --force"
  ],
  "warnings": [
    "history contains merge commits; a plain rebase will flatten them",
    "branch is published; rewriting it rewrites history others may have based work on"
  ]
}

退出代码：成功时为 0，发生运行时错误（包括输入文件无法读取或无效，以及输入无效）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/rebaseplan mcp

MCP 客户端配置：

{
  "mcpServers": {
    "rebaseplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/rebaseplan", "mcp"]
    }
  }
}

工具

• plan_rebase — 在开始前规划安全的变基。

  • commits（数组，必填，不能为空）——该分支自己的提交，按从旧到新的顺序排列：{hash, subject, merge}
  • upstream_commits（数组，可选，默认为 []）——上游分支有而该分支没有的提交： {hash, subject}
  • published（布尔值，可选，默认为 false）——该分支是否已推送或共享

  返回 {commit_count, merge_commits, squash_markers, upstream_new_commits, published, force_push_risk, recommended_strategy, steps, warnings}。

Docker

docker run -i ghcr.io/cloudcorprecords/rebaseplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/rebaseplan plan --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios