gitcleanplan

gitcleanplan

分支列表会悄悄变长。功能上线了，分支却留了下来； 实验被放弃了，分支也留了下来；上游消失了，本地副本 仍然存在。凭猜测删除分支可能会导致工作丢失，因此 gitcleanplan 选择了折中方案：你提供分支数据，它返回 一个计划——先列出，不删除任何内容。

对于你提供的每个分支，计划会给出以下三种决策之一， 并说明做出决策的原因：

• keep — 默认分支、受保护的分支、当前检出的 分支，或仍在活跃使用的分支。
• review — 已合并但近期仍活跃、上游已消失但尚未 合并，或长期未更新但尚未合并的分支：这些都是有希望的清理 候选项，在采取其他操作前值得人工检查。
• delete — 已合并，且上游已消失或至少有 stale_days 天未更新。只有已合并的分支才会被列入此项。

决策遵循固定的规则顺序，因此原因始终明确：默认分支 优先于保护规则，保护规则优先于已合并且上游已消失的分支， 当前检出的分支优先于已合并的分支，而“已合并且上游 已消失”优先于“已合并且长期未更新”。长期未更新的判定 包含边界值——最后一次提交恰好是在 stale_days 天前 的分支也算长期未更新。

除了逐个分支的决策外，结果还会按操作归类分支名称、 统计数量，并按名称顺序为计划删除的每个分支列出一条 安全删除命令（git branch -d <name>）。这些命令只会 列出，绝不会执行：gitcleanplan 不会调用 git、 打开仓库或删除任何内容。你阅读计划，然后自行决定 要执行什么操作。

格式错误的输入——缺失或为空的分支列表、缺失、 为空或重复的分支名称、缺失、为负数或非整数的 last_commit_days_ago、类型错误的标志、无效的 stale_days 或 default_branch——会触发验证错误， 并指出出错的路径（例如 branches[1].last_commit_days_ago must be an integer >= 0）， 不会生成部分计划。计算是纯本地操作：不访问网络、不使用配置， 也不会读取你传入的输入以外的文件。

CLI

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

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

{
  "stale_days": 90,
  "branches": [
    { "name": "main", "last_commit_days_ago": 0, "current": true },
    { "name": "shipped-feature", "merged": true, "upstream_gone": true, "last_commit_days_ago": 45 },
    { "name": "old-spike", "last_commit_days_ago": 180 }
  ]
}

每个分支的 merged、upstream_gone、protected 和 current 默认值为 false；stale_days 默认值为 90；default_branch 默认值为 "main"。计划会以 JSON 格式输出：

{
  "branches": [
    { "name": "main", "action": "keep", "reason": "default branch" },
    { "name": "old-spike", "action": "review", "reason": "stale but not merged" },
    { "name": "shipped-feature", "action": "delete", "reason": "merged and upstream is gone" }
  ],
  "plan": {
    "delete": ["shipped-feature"],
    "review": ["old-spike"],
    "keep": ["main"]
  },
  "counts": { "delete": 1, "review": 1, "keep": 1 },
  "commands": ["git branch -d shipped-feature"]
}

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

MCP 服务

npx -y @reneturcios/gitcleanplan mcp

MCP 客户端配置：

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

工具

• plan_branch_cleanup — 规划清理长期未更新且已合并的分支。

  • branches（数组，必填，至少一个元素）— 分支列表，每项为 {name, last_commit_days_ago, merged?, upstream_gone?, protected?, current?} 对象；name 在集合中必须唯一， last_commit_days_ago 是大于或等于 0 的整天数
  • stale_days（整数，可选，默认值为 90，至少为 1） — 分支距上次提交达到此天数时即视为长期未更新
  • default_branch（字符串，可选，默认值为 "main"）— 默认分支名称；绝不会计划删除该分支

  返回 {branches, plan, counts, commands}。

Docker

docker run -i ghcr.io/cloudcorprecords/gitcleanplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/gitcleanplan 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