branchname

branchname

分支命名听起来很简单，直到每位贡献者都各自为政：fix-login、123-login-bug、johns-branch，还有同一问题的十几种变体，没法用同一种方式通过 grep 搜索。branchname 采用了另一种方式——你把问题交给它，它就会按照仓库一贯的方式返回一个名称。

标题会按固定且锁定的规则转换为 slug：将其转为小写，把每段最长的非 [a-z0-9] 字符序列替换为单个 -，然后去掉开头和结尾的 -。连续标点会合并，而不是产生多个连字符；数字会保留；ASCII 以外的字符——重音符号、破折号、表情符号——都和其他标点一样视为分隔符。如果标题中完全没有可用于生成 slug 的内容，就会报错（“title produces an empty slug”），而不会生成名为 - 的分支。

slug 过长时会被截断：精确截取到 max_slug_length 个字符（默认 40，最低为 8），然后去掉截断后留下的尾部 -，这样分支名称就不会以悬空连字符结尾，导致单词被截断。

接着，slug 会按以下四种约定之一组合：

• type-issue-slug（默认）—— <type>/<issue_number>-<slug>，例如 fix/123-login-redirect-loop。需要同时提供 type 和 issue_number。
• type-slug —— <type>/<slug>，例如 docs/update-install-guide。需要提供 type。
• issue-slug —— <issue_number>-<slug>，例如 42-login-redirect-loop。需要提供 issue_number。
• slug —— 仅 <slug>，例如 login-redirect-loop。不需要提供其他字段。

type 必须是 feat、fix、chore、docs、refactor 或 test。如果所选约定需要某个未提供的组成部分，就会报错并指出该组成部分；输入格式错误时——title 缺失、为空或不是字符串，issue_number 不是大于或等于 1 的整数，type 或 convention 不在其枚举范围内，或 max_slug_length 不是大于或等于 8 的整数——会产生验证错误，指出有问题的路径，且不返回部分结果。计算过程纯粹且在本地执行：不会访问网络、读取配置，也不会读取或改动仓库——branchname 只负责生成名称。

命令行

npx @reneturcios/branchname make --input args.json
npx @reneturcios/branchname --version

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

{
  "title": "Fix login redirect loop",
  "issue_number": 123,
  "type": "fix"
}

convention 默认为 "type-issue-slug"，max_slug_length 默认为 40。结果将以 JSON 格式打印：

{
  "branch": "fix/123-fix-login-redirect-loop",
  "slug": "fix-login-redirect-loop",
  "convention": "type-issue-slug"
}

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

MCP 服务

npx -y @reneturcios/branchname mcp

MCP 客户端配置：

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

工具

• make_branch_name — 根据问题标题生成分支名称。

  • title（字符串，必填，不能为空）——要转换为 slug 的问题标题
  • issue_number（整数，可选，至少为 1）——问题编号
  • type（字符串，可选）——更改类型前缀，必须是 feat、fix、chore、docs、refactor、test 之一
  • convention（字符串，可选，默认为 "type-issue-slug"）——必须是 type-issue-slug、 type-slug、issue-slug、slug 之一
  • max_slug_length（整数，可选，默认为 40，至少为 8）——截断前 slug 的最大长度

  返回 {branch, slug, convention}，其中 slug 是最终的（可能经过截断的）slug，convention 会回显最终采用的约定。

Docker

docker run -i ghcr.io/cloudcorprecords/branchname
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/branchname make --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 — Copyright (c) 2026 Rene Turcios