create-branch-cli

一个快速创建 Git 分支的命令行工具，支持自动生成规范的分支名称。

功能特性

• 🚀 快速创建 Git 分支
• 📝 自动生成规范的分支名称
• 👤 首次使用自动保存用户信息（工号、姓名）
• 🐛 支持 feature 和 hotfix 两种分支类型
• 📅 自动添加日期后缀
• 💾 支持保存需求唯一标识，快速提交和推送
• 🎯 支持为不同项目配置不同的目标分支（如 master 或 main）
• 🔄 支持 push 后自动轮询检查合并状态
• 🔍 支持监听 GitLab 合并请求状态，合并后自动拉取最新目标分支代码

分支命名规则

• Feature 分支: feature/工号_姓名_需求标题_年月日
• HotFix 分支: hotfix/工号_姓名_需求标题_年月日

示例：

• feature/001_张三_用户登录功能_20251226
• hotfix/001_张三_修复登录bug_20251226

安装

本地开发安装

npm install -g

或者使用 npm link（在项目目录下）：

npm link

发布到 npm（发布后其他人可全局安装）

npm publish

发布后，其他人可以通过以下命令安装：

npm install -g create-branch-cli

使用方法

首次使用

首次使用时，工具会提示您输入工号和姓名，这些信息会保存在 ~/.create-branch/config.json 文件中。

创建 Feature 分支

# 仅创建分支
create-branch 用户登录功能
# 或使用别名
cb 用户登录功能

# 创建分支并保存需求唯一标识（用于后续快速提交）
create-branch 用户登录功能 PROJ-123
# 或使用别名
cb 用户登录功能 PROJ-123

创建 HotFix 分支

# 仅创建分支
create-branch 修复登录bug -b
# 或
create-branch 修复登录bug --bug
# 或使用别名
cb 修复登录bug -b

# 创建分支并保存需求唯一标识
create-branch 修复登录bug PROJ-124 -b
# 或使用别名
cb 修复登录bug PROJ-124 -b

快速提交和推送

如果创建分支时输入了需求唯一标识，可以使用以下命令快速提交和推送：

create-branch push
# 或使用别名
cb push

说明：

• 会自动添加所有更改到暂存区
• 提交信息格式：需求唯一标识:需求标题（例如：PROJ-123:用户登录功能）
• 自动推送到远程仓库的当前分支
• 首次使用时，会提示设置当前项目的目标分支（如 master 或 main）
• 如果启用了自动同步（autoSyncMaster），push 后会自动开始轮询检查合并状态
• 轮询检测到合并后会自动切换到目标分支并拉取最新代码

配置用户信息

如果需要修改工号、姓名或配置选项，可以使用以下命令：

create-branch config
# 或使用别名
cb config

说明：

• 会提示输入新的工号和姓名
• 可以配置是否启用合并后自动拉取目标分支（需要配置 GitLab 信息）
• 如果启用了自动同步，push 后会自动开始轮询检查合并状态
• 配置后，之前保存的需求信息会保留
• 新创建的分支将使用新的工号和姓名

设置目标分支

设置当前项目的目标分支（例如：master 或 main），用于自动创建合并请求和拉取最新代码。

create-branch set-target
# 或使用别名
cb set-target

说明：

• 首次使用 push 命令时会自动提示设置
• 设置后的目标分支名会保存在配置文件中
• 每个项目可以有不同的目标分支

检查合并状态并同步目标分支

如果启用了 GitLab 自动同步功能，可以使用以下命令手动检查当前分支的合并请求状态：

create-branch sync
# 或
create-branch check
# 或使用别名
cb sync
# 或
cb check

说明：

• 检查当前分支的合并请求是否已合并到目标分支
• 如果已合并，自动切换到目标分支并拉取最新代码
• 如果未合并，显示合并请求状态和链接

轮询检查合并状态

由于合并请求是在 GitLab 上手动操作的，工具无法实时知道合并状态。可以使用轮询功能定期检查：

# 默认每30秒检查一次，直到合并或手动停止（Ctrl+C）
create-branch watch
# 或
cb watch

# 指定检查间隔（秒）
cb watch 60          # 每60秒检查一次

# 指定检查间隔和最大检查次数
cb watch 30 60      # 每30秒检查一次，最多检查60次（30分钟）

# 指定分支名、间隔和最大次数
cb watch feature/xxx_xxx_xxx_20251226 30 60

说明：

• 轮询会定期检查合并请求状态
• 一旦检测到合并，会自动切换到目标分支并拉取最新代码
• 可以使用 Ctrl+C 随时停止轮询
• 建议在 push 代码并创建合并请求后使用此功能

查看帮助

create-branch
# 或
cb

配置

用户信息和需求信息保存在 ~/.create-branch/config.json 文件中，格式如下：

{
  "workId": "001",
  "name": "张三",
  "autoSyncMaster": false,
  "gitlab": {
    "url": "https://gitlab.com",
    "token": "your-personal-access-token"
  },
  "projects": {
    "group_project": {
      "targetBranch": "master"
    }
  },
  "requirements": {
    "feature/001_张三_用户登录功能_20251226": {
      "id": "PROJ-123",
      "title": "用户登录功能",
      "branchName": "feature/001_张三_用户登录功能_20251226"
    }
  }
}

配置说明：

• workId: 工号
• name: 姓名
• autoSyncMaster: 是否启用合并后自动拉取目标分支（默认：false）
• gitlab: GitLab 配置（仅在启用自动同步时需要）
  • url: GitLab 服务器地址（例如：https://gitlab.com）
  • token: GitLab Personal Access Token（需要 api 权限）
• projects: 项目配置（以项目路径或 ID 为 key）
  • targetBranch: 项目的目标分支（如 master 或 main）
• requirements: 需求信息（以分支名为 key，自动保存）

GitLab Personal Access Token 获取方法：

1. 登录 GitLab
2. 进入 Settings → Access Tokens
3. 创建新的 Personal Access Token
4. 勾选 api 权限
5. 复制生成的 token

如果需要修改用户信息，可以：

1. 使用 cb config 命令（推荐）
2. 直接编辑配置文件
3. 删除配置文件，下次使用时重新录入

注意事项

1. 使用前请确保当前目录是一个 Git 仓库
2. 如果分支已存在，工具会提示是否切换到已存在的分支
3. 需求标题中的空格会自动替换为下划线
4. 日期格式为 YYYYMMDD（例如：20251226）
5. 使用 cb push 前，请确保创建分支时输入了需求唯一标识
6. cb push 会自动添加所有更改并提交，提交信息格式：需求唯一标识:需求标题
7. 启用自动同步功能需要配置 GitLab Personal Access Token（需要 api 权限）
8. 自动同步功能会通过 GitLab API 检查合并请求状态，需要网络连接
9. 重要：如果启用了自动同步，push 后会自动开始轮询检查合并状态（每30秒检查一次）
10. 轮询会在后台运行，检测到合并后会自动切换到目标分支并拉取最新代码
11. 如果切换了分支，轮询会自动停止
12. 可以使用 Ctrl+C 随时停止轮询，或使用 cb sync 手动检查一次
13. 每个项目需要设置一次目标分支（set-target 或首次 push 时），支持 master、main 等不同分支名

许可证

ISC