Commit Prefix Helper

一个 VSCode 插件，用于自动从 Git 分支名称提取 scope 并生成符合规范的 commit message 前缀。

预览效果

📖 简介

Commit Prefix Helper 是一个专为团队协作开发的 VSCode 插件，它能够：

🔍 自动提取 scope：从当前 Git 分支名称自动提取 scope（如 feature/userCenter → userCenter）
📝 便捷的 type 选择：通过下拉菜单快速选择 commit type
🎨 预设模板：支持配置预设的 commit 模板，支持完整前缀或带后缀的模板（如 chore(release): 或 refactor(scope): CR-）
⚙️ 灵活的配置：支持仓库级别和全局配置，可自定义 type 列表和提取规则
🎯 符合规范：自动生成 {type}({scope}): 格式的前缀
🚀 无缝集成：在 Source Control 面板中直接使用，无需切换视图

✨ 功能特性

核心功能

分支名称解析
- 自动从分支名称提取 scope
- 支持自定义提取规则（正则表达式）
- 分支名称不符合规范时，支持手动输入 scope
Type 类型选择
- 提供默认的 commit type 列表
- 支持自定义 type 列表（仓库级别或全局）
- 通过 QuickPick 下拉菜单快速选择
前缀自动生成
- 自动生成 {type}({scope}): 格式的前缀
- 自动插入到 Git commit message 输入框的最前面
- 保留用户已输入的内容
预设模板支持
- 支持配置预设的 commit 模板
- 模板会出现在 type 选择列表中，label 格式为 "模板-xxx"
- 如果模板有 suffix 字段，会从分支动态提取 scope，生成格式：{type}({scope}): {suffix}
- 如果模板没有 suffix 字段，value 是完整前缀，直接使用，无需从分支提取 scope

UI 集成

Source Control 面板按钮：在 Source Control 面板标题栏右侧显示 "插入 Commit 前缀" 按钮
状态栏按钮：在状态栏右侧显示快捷入口（备用）
命令面板：支持通过命令面板调用

🚀 快速开始

安装

方式一：从 VSIX 文件安装（推荐）

下载 commit-prefix-helper_X.X.X.vsix 文件
在 VSCode 中按 Ctrl+Shift+P（Mac: Cmd+Shift+P）
输入 "Extensions: Install from VSIX..."
选择下载的 .vsix 文件

方式二：从源码安装

# 克隆仓库
git clone <repository-url>
cd commit-prefix-helper

# 安装依赖
pnpm install

# 编译
pnpm run compile

# 打包
pnpm run package:local

# 安装生成的 .vsix 文件
code --install-extension commit-prefix-helper_X.X.X.vsix

基本使用

打开 Source Control 面板
- 按 Ctrl+Shift+G（Mac: Cmd+Shift+G）
- 或点击左侧活动栏的 Source Control 图标
点击插入前缀按钮
- 在 Source Control 面板标题栏右侧，找到 "插入 Commit 前缀" 按钮（带编辑图标）
- 点击该按钮
选择 commit type
- 在弹出的下拉菜单中选择合适的 commit type
- 例如：feat（新功能）、fix（修复bug）等
自动插入前缀
- 插件会自动提取当前分支的 scope
- 生成 {type}({scope}): 格式的前缀
- 自动插入到 commit message 输入框的最前面
输入变更描述
- 前缀已插入，继续输入你的变更描述
- 例如：feat(userCenter): 添加用户中心页面

使用示例

示例 1：标准分支名称

假设当前分支为 feature/userCenter：

点击 "插入 Commit 前缀" 按钮
选择 feat（新功能）
自动生成：feat(userCenter):
继续输入：feat(userCenter): 添加用户中心页面

示例 2：分支名称不符合规范

假设当前分支为 main（没有斜杠）：

点击 "插入 Commit 前缀" 按钮
选择 feat
插件提示：分支不符合规范，是否手动输入 scope？
选择 "手动输入"，输入 userCenter
自动生成：feat(userCenter):

示例 3：使用预设模板（无后缀）

假设配置了发版模板 chore(release): ：

点击 "插入 Commit 前缀" 按钮
在 type 选择列表中选择 "模板-发版"
自动生成：chore(release):
继续输入版本号：chore(release): 0.2.0

注意：无后缀的模板使用完整前缀，不会从分支名称提取 scope。

示例 4：使用预设模板（带后缀）

假设配置了重构CR模板，当前分支为 feature/userCenter：

点击 "插入 Commit 前缀" 按钮
在 type 选择列表中选择 "模板-重构CR"
自动生成：refactor(userCenter): CR-（scope 从分支动态提取）
继续输入：refactor(userCenter): CR-12345

注意：带后缀的模板会从分支名称动态提取 scope。

示例 5：使用命令面板

按 Ctrl+Shift+P（Mac: Cmd+Shift+P）
输入 "Insert Commit Prefix"
选择 commit type 或模板
前缀自动插入

⚙️ 配置

配置优先级

配置优先级从高到低：仓库配置 > 全局配置 > 默认配置

仓库级别配置

在项目根目录创建 .vscode/commit-prefix-config.json：

提示：可以参考项目中的 .vscode/commit-prefix-config.json.example 示例文件。

{
  "types": [
    {
      "value": "feat",
      "label": "新功能",
      "description": "添加新功能"
    },
    {
      "value": "fix",
      "label": "修复bug",
      "description": "修复问题"
    },
    {
      "value": "style",
      "label": "样式调整",
      "description": "样式相关变更"
    },
    {
      "value": "refactor",
      "label": "重构",
      "description": "代码重构"
    },
    {
      "value": "chore",
      "label": "构建工具",
      "description": "构建过程或辅助工具变动"
    },
    {
      "value": "pkg",
      "label": "包管理",
      "description": "包管理相关"
    }
  ],
  "branchPattern": ".*",
  "scopeExtractPattern": "^[^/]+/(.+)$",
  "templates": [
    {
      "value": "chore(release): ",
      "label": "模板-发版",
      "description": "发版提交：chore(release): "
    },
    {
      "value": "refactor",
      "label": "模板-重构CR",
      "suffix": "CR-",
      "description": "重构提交：refactor(scope): CR-xxx"
    },
    {
      "value": "fix",
      "label": "模板-疑难问题",
      "suffix": "疑难问题修复-",
      "description": "疑难问题修复：fix(scope): 疑难问题修复-xxx"
    }
  ]
}

全局配置

在 VSCode 设置（settings.json）中配置：

{
  "commitPrefixHelper.types": [
    { "value": "feat", "label": "新功能", "description": "添加新功能" },
    { "value": "fix", "label": "修复bug", "description": "修复问题" },
    { "value": "style", "label": "样式调整", "description": "样式相关变更" },
    { "value": "refactor", "label": "重构", "description": "代码重构" },
    { "value": "chore", "label": "构建工具", "description": "构建过程或辅助工具变动" },
    { "value": "pkg", "label": "包管理", "description": "包管理相关" }
  ],
  "commitPrefixHelper.branchPattern": ".*",
  "commitPrefixHelper.scopeExtractPattern": "^[^/]+/(.+)$",
  "commitPrefixHelper.templates": [
    {
      "value": "chore(release): ",
      "label": "模板-发版",
      "description": "发版提交：chore(release): "
    },
    {
      "value": "refactor",
      "label": "模板-重构CR",
      "suffix": "CR-",
      "description": "重构提交：refactor(scope): CR-xxx"
    },
    {
      "value": "fix",
      "label": "模板-疑难问题",
      "suffix": "疑难问题修复-",
      "description": "疑难问题修复：fix(scope): 疑难问题修复-xxx"
    }
  ]
}

配置项说明

skipBranchValidation

是否跳过分支名称验证。当设置为 true 时，如果无法从分支名称提取 scope，会直接使用空 scope（格式为 type: message），而不是提示用户手动输入。

默认值：false
类型：boolean
适用场景：个人项目、不想遵守严格分支规范的项目

示例：

{
  "skipBranchValidation": true
}

allowedBranches

允许直接提交的分支名称白名单。如果当前分支名在此列表中，会跳过分支验证，直接使用空 scope。

默认值：[]（空数组）
类型：string[]
适用场景：特定分支（如 main、master）不需要遵守分支规范

示例：

{
  "allowedBranches": ["main", "master", "develop"]
}

注意：

skipBranchValidation 和 allowedBranches 是"或"的关系
只要任一条件满足，就会跳过分支验证
当跳过验证时，会使用空 scope，生成格式为 type: message

prefixInsertMode

前缀插入模式，控制如何在 commit message 中添加前缀。

默认值："prepend"
类型："prepend" | "replace"
可选值：
- "prepend"：在现有消息前添加前缀（默认行为）
- "replace"：替换现有消息中的前缀

示例：

{
  "prefixInsertMode": "prepend"
}

或

{
  "prefixInsertMode": "replace"
}

说明：

prepend 模式（默认）

在现有 commit message 最前面添加新前缀
如果已有前缀，会重复添加
适用于首次添加前缀

示例：

原始消息：添加用户登录功能
选择 feat(userCenter)
结果：feat(userCenter): 添加用户登录功能

如果再次选择 fix(userCenter)
结果：fix(userCenter): feat(userCenter): 添加用户登录功能

replace 模式

替换现有消息中的前缀
自动识别并替换符合规范的前缀
适用于修改 commit type

示例：

原始消息：feat(userCenter): 添加用户登录功能
选择 fix(userCenter)
结果：fix(userCenter): 添加用户登录功能

如果再选择 style(userCenter)
结果：style(userCenter): 添加用户登录功能

使用场景：

prepend：个人项目、首次提交、不需要修改 type
replace：团队项目、需要频繁修改 type、规范更严格

types

commit type 列表，每个 type 包含：

value（必需）：commit type 的值，如 feat、fix
label（必需）：显示名称，如 新功能、修复bug
description（可选）：详细描述

branchPattern

分支名称匹配模式（正则表达式），用于验证分支名称是否符合规范。

默认值：".*"（匹配所有分支）
示例："^(feature|fix|hotfix|refactor)/.+$"（只匹配特定前缀的分支）

scopeExtractPattern

scope 提取模式（正则表达式），第一个捕获组为 scope。

默认值："^[^/]+/(.+)$"（提取斜杠后的内容）
示例：
- "^[^/]+/(.+)$" → feature/userCenter → userCenter
- "^(.+)-(.+)$" → feature-userCenter → userCenter（第二个捕获组）

templates

预设的 commit 模板列表，结构和 types 一致。支持两种模式：

模式1：无后缀模板（完整前缀）

value 是完整的前缀（如 "chore(release): "），选择后直接使用
不需要从分支提取 scope
适用于固定格式的提交

模式2：带后缀模板（动态 scope）

value 是 type 值（如 "refactor"、"fix"）
suffix 是后缀（如 "CR-"、"疑难问题修复-"）
会从分支动态提取 scope，生成格式：{type}({scope}): {suffix}
适用于需要动态 scope 但固定后缀的提交

每个模板包含：

value（必需）：
- 无后缀模板：完整的前缀，如 "chore(release): "
- 带后缀模板：type 值，如 "refactor"、"fix"
label（必需）：显示名称，建议格式为 "模板-xxx"，如 "模板-发版"、"模板-重构CR"
description（可选）：详细描述
suffix（可选）：后缀，如 "CR-"、"疑难问题修复-"。如果存在，会从分支动态提取 scope

使用场景：

无后缀模板（固定格式）：
- 发版提交：chore(release): 0.2.0
- 文档更新：docs(readme): 更新使用说明
带后缀模板（动态 scope + 固定后缀）：
- 重构CR：refactor(userCenter): CR-12345（scope 从分支提取）
- 疑难问题修复：fix(paymentBug): 疑难问题修复-修复支付失败问题（scope 从分支提取）

注意：

模板会出现在 type 选择列表中，label 建议使用 "模板-" 前缀以便区分
无后缀模板：直接使用 value 作为前缀，不会从分支名称提取 scope
带后缀模板：会从分支名称动态提取 scope，生成格式：{type}({scope}): {suffix}
如果无法提取 scope，会提示用户手动输入或使用空 scope（格式：{type}: {suffix}）

默认 Type 列表

插件提供以下默认 commit type：

feat - 新功能
fix - 修复bug
style - 样式调整
refactor - 重构
chore - 构建工具
pkg - 包管理

默认模板列表

插件提供以下默认模板：

chore(release): - 发版提交（label: "模板-发版"）
- 类型：无后缀模板
- 使用：直接使用完整前缀

模板会在 type 选择列表中显示。无后缀模板直接使用完整前缀，带后缀模板会从分支动态提取 scope。

📝 分支名称规范

支持的格式

插件默认支持以下格式的分支名称：

feature/userCenter → scope: userCenter
fix/paymentBug → scope: paymentBug
hotfix/criticalIssue → scope: criticalIssue
refactor/storeManagement → scope: storeManagement
chore/updateDependencies → scope: updateDependencies

自定义格式

通过配置 scopeExtractPattern 可以支持其他格式：

feature-userCenter → 配置："^[^-]+-(.+)$" → scope: userCenter
userCenter → 配置："^(.+)$" → scope: userCenter

不符合规范的处理

如果分支名称不符合配置的规则：

插件会提示：当前分支不符合规范，无法自动提取 scope
提供选项：是否手动输入 scope？
如果选择手动输入，会弹出输入框让用户输入 scope

⚠️ 使用注意事项

1. Git 仓库要求

插件只在 Git 仓库中工作
如果当前不在 Git 仓库中，按钮可能不显示或点击时会有提示

2. 分支名称规范

建议使用 type/scope 格式的分支名称（如 feature/userCenter）
如果分支名称不符合规范，需要手动输入 scope

3. Commit Message 格式

插件生成的前缀格式：{type}({scope}):
注意：前缀后面有一个空格，这是符合 Conventional Commits 规范的
前缀会插入到输入框的最前面，保留已输入的内容

4. 模板使用

无后缀模板：value 是完整的前缀，选择后直接使用，不会从分支名称提取 scope
带后缀模板：value 是 type 值，suffix 是后缀，会从分支名称动态提取 scope，生成格式：{type}({scope}): {suffix}
模板 label 建议使用 "模板-" 前缀以便区分
模板会出现在 type 选择列表的最后
如果带后缀模板无法提取 scope，会提示用户手动输入或使用空 scope

5. 配置优先级

仓库配置优先级最高，适合团队统一规范
全局配置适合个人偏好设置
默认配置作为兜底方案

6. 性能考虑

插件激活时间 < 100ms
分支解析时间 < 50ms
UI 响应时间 < 200ms

🛠️ 开发

项目结构

commit-prefix-helper/
├── src/
│   ├── extension.ts              # 插件入口
│   ├── git/
│   │   ├── gitService.ts        # Git 操作服务
│   │   └── branchParser.ts      # 分支解析器
│   ├── config/
│   │   ├── configManager.ts     # 配置管理器
│   │   └── defaultConfig.ts     # 默认配置
│   ├── ui/
│   │   ├── sourceControlButton.ts  # Source Control 按钮
│   │   └── typePicker.ts       # Type 选择器
│   └── utils/
│       └── messageFormatter.ts  # 消息格式化
├── resources/
│   └── icon.svg                 # 图标文件
├── scripts/
│   ├── package-local.js         # 本地打包脚本
│   └── release.js                # Release 脚本
├── package.json
├── tsconfig.json
├── webpack.config.js
└── README.md

开发环境要求

Node.js >= 18.0.0
pnpm >= 8.0.0（推荐）或 npm >= 9.0.0
VSCode >= 1.60.0

安装依赖

# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install

开发命令

# 编译（生产模式）
pnpm run compile

# 监听模式编译（开发模式）
pnpm run watch

# 本地打包（生成 commit-prefix-helper_X.X.X.vsix）
pnpm run package:local

# 打包（不指定版本号）
pnpm run package

调试

启动调试
- 按 F5 打开新的 VSCode 窗口（Extension Development Host）
- 在新窗口中测试插件功能
查看日志
- 打开输出面板：View → Output 或 Ctrl+Shift+U（Mac: Cmd+Shift+U）
- 选择 "Log (Extension Host)"
- 查看 "Commit Prefix Helper" 相关的日志
调试技巧
- 在代码中添加 console.log() 查看调试信息
- 使用 VSCode 的调试功能设置断点
- 查看开发者工具：Help → Toggle Developer Tools

打包

本地打包

# 编译并打包，自动根据 package.json 版本号生成包名
pnpm run package:local

# 生成文件：commit-prefix-helper_0.1.8.vsix

Release 打包（自动提交版本变更）

# Patch 版本（0.1.8 -> 0.1.9）
pnpm run release:patch

# Minor 版本（0.1.8 -> 0.2.0）
pnpm run release:minor

# Major 版本（0.1.8 -> 1.0.0）
pnpm run release:major

Release 脚本会自动：

更新 package.json 中的版本号
编译代码
打包生成 .vsix 文件
自动提交版本变更（commit message: chore(release): X.X.X）

测试

功能测试
- 在不同格式的分支名称下测试
- 测试配置文件的读取和优先级
- 测试错误处理（如不在 Git 仓库中）
边界情况
- 分支名称为 main、master 等（无斜杠）
- 分支名称包含特殊字符
- 配置文件格式错误

📦 打包说明

打包流程

编译代码
```
pnpm run compile
```
打包插件
```
pnpm run package:local
```
安装插件
- 在 VSCode 中：Extensions: Install from VSIX...
- 或命令行：code --install-extension commit-prefix-helper_X.X.X.vsix

打包配置

打包工具：@vscode/vsce
输出格式：.vsix 文件
包名格式：commit-prefix-helper_{version}.vsix
自动排除：src/、node_modules/、.git/ 等开发文件

打包注意事项

版本号管理
- 版本号在 package.json 中定义
- Release 脚本会自动更新版本号并提交
依赖处理
- 使用 --no-dependencies 选项，不包含 node_modules
- 插件只依赖 VSCode API，无需额外依赖
文件包含
- 确保 resources/ 目录被包含（图标文件）
- 检查 .vscodeignore 文件配置

🔧 故障排查

问题：按钮不显示

可能原因：

插件未激活
不在 Git 仓库中
Source Control 面板未打开

解决方法：

检查插件是否已启用：Extensions → 搜索 "Commit Prefix Helper"
确保在 Git 仓库中打开项目
打开 Source Control 面板：Ctrl+Shift+G

问题：无法提取 scope

可能原因：

分支名称不符合配置的规则
scopeExtractPattern 配置错误

解决方法：

检查分支名称格式
检查 .vscode/commit-prefix-config.json 或全局配置
使用手动输入 scope 功能

问题：前缀未插入

可能原因：

Git 扩展未加载
commit message 输入框不可用

解决方法：

等待 Git 扩展加载完成
确保 Source Control 面板已打开
检查输出面板的日志信息

问题：配置不生效

可能原因：

配置文件格式错误
配置文件位置不正确
配置优先级问题

解决方法：

检查 JSON 格式是否正确
仓库配置应在 .vscode/commit-prefix-config.json
检查配置优先级：仓库配置 > 全局配置 > 默认配置

📋 系统要求

VSCode 版本：>= 1.60.0
操作系统：Windows、macOS、Linux
Git：需要安装 Git 并配置

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
提交更改：git commit -m 'feat: Add some feature'
推送到分支：git push origin feature/your-feature
提交 Pull Request

代码规范

使用 TypeScript
遵循 ESLint 规则
添加必要的注释
编写清晰的 commit message

📚 相关资源

🎯 路线图

[ ] 支持 commit message 模板
[ ] 支持历史 commit type 记忆和推荐
[ ] 支持多 scope 选择（适用于复杂分支）
[ ] 支持 commit message 验证和提示
[ ] 快捷键支持
[ ] 状态栏显示当前 scope
[ ] 可视化配置界面

Made with ❤️ for better Git commits

Commit Prefix Helper

Jsmond2016

Commit Prefix Helper

预览效果

📖 简介

✨ 功能特性

核心功能

UI 集成

🚀 快速开始

安装

方式一：从 VSIX 文件安装（推荐）

方式二：从源码安装

基本使用

使用示例

示例 1：标准分支名称

示例 2：分支名称不符合规范

示例 3：使用预设模板（无后缀）

示例 4：使用预设模板（带后缀）

示例 5：使用命令面板

⚙️ 配置

配置优先级

仓库级别配置

全局配置

配置项说明

skipBranchValidation

allowedBranches

prefixInsertMode

types

branchPattern

scopeExtractPattern

templates

默认 Type 列表

默认模板列表

📝 分支名称规范

支持的格式

自定义格式

不符合规范的处理

⚠️ 使用注意事项

1. Git 仓库要求

2. 分支名称规范

3. Commit Message 格式

4. 模板使用

5. 配置优先级

6. 性能考虑

🛠️ 开发

项目结构

开发环境要求

安装依赖

开发命令

调试

打包

本地打包

Release 打包（自动提交版本变更）

测试

📦 打包说明

打包流程

打包配置

打包注意事项

🔧 故障排查

问题：按钮不显示

问题：无法提取 scope

问题：前缀未插入

问题：配置不生效

📋 系统要求

📄 许可证

🤝 贡献

贡献指南

代码规范

📚 相关资源

🎯 路线图