git-commit-guard

一个用于规范 Git 提交信息的轻量级工具，同时提供 VS Code 扩展命令。支持 GitHub 和 GitLab 仓库。

它提供两类能力：

commit-msg hook 校验提交信息是否符合团队规范
prompt 交互式生成 commit message，减少手输出错
VS Code 命令面板里生成和校验 commit message
支持通过 benchamark 关键词触发 benchmark test

默认规范

默认采用以下格式：

<type>(<scope>): <subject>

Refs: [#123](https://github.com/your-account/git-commit-guard/issues/123)

示例：

feat(user): add login audit log

Refs: [#128](https://github.com/your-account/git-commit-guard/issues/128)

或：

fix: resolve null pointer on profile query

Closes: [group/project#245](https://github.com/group/project/issues/245)

如果需要触发 benchmark test，可以追加一行：

benchamark

或者带一个或多个 tag：

benchamark tag: smoke, release

VS Code 用法

安装扩展后，在命令面板中运行：

Git Commit Guard: Generate Commit Message
Git Commit Guard: Validate Commit Message

生成命令会：

引导你依次输入 type、scope、subject、issue
如果开启了 benchmark 配置，还会询问是否追加 benchamark
会在填写前从可配置的后台拉取可选 tag 列表
自动生成 commit message
自动复制到剪贴板
在新的编辑器标签页中打开结果

校验命令会：

校验当前编辑器全文
如果有选中文本，则只校验选中内容

可用命令

安装 hook：

node ./bin/git-commit-guard.js install

校验单条提交信息：

node ./bin/git-commit-guard.js validate --message "feat(api): add order query"

交互式生成提交信息：

node ./bin/git-commit-guard.js prompt

直接发起 git commit：

node ./bin/git-commit-guard.js prompt --commit

配置

CLI 模式下，可以在仓库根目录放置 .git-commit-guard.json：

{
  "requireScope": false,
  "requireIssue": true,
  "issuePrefixes": ["Refs", "Closes"],
  "benchmark": {
    "enabled": true,
    "keyword": "benchamark",
    "tagLabel": "tag",
    "tagApiUrl": "https://example.com/api/benchmark/tags",
    "tagRequestHeaders": {
      "Authorization": "Bearer <token>"
    },
    "tagResponsePath": "data.tags",
    "tagNameField": "name"
  }
}

接口返回支持两种常见格式：

["smoke", "release", "ios"]

或：

{
  "data": {
    "tags": [
      { "name": "smoke" },
      { "name": "release" }
    ]
  }
}

说明：

benchmark.enabled 为 true 时才会启用 benchmark 交互和校验
benchmark.keyword 默认是 benchamark
benchmark.tagApiUrl 配置后会在生成 commit message 前在线拉取 tags
benchmark.tagResponsePath 用于从接口返回中找到 tag 数组
benchmark.tagNameField 用于从对象数组中取 tag 名称

VS Code / Cursor 中配置校验规则（用户可配置）

如果是扩展使用者，不需要改仓库文件，可以直接在编辑器设置里配置。
扩展会按以下优先级读取配置：

VS Code / Cursor Settings (gitCommitGuard.*)
仓库内 .git-commit-guard.json（或其他同名配置文件）
内置默认值

常用可配置校验项：

gitCommitGuard.types
gitCommitGuard.requireScope
gitCommitGuard.requireIssue
gitCommitGuard.issuePrefixes
gitCommitGuard.subjectMinLength
gitCommitGuard.subjectMaxLength
gitCommitGuard.maxHeaderLength

打开 Settings，搜索 Git Commit Guard，然后设置：

gitCommitGuard.benchmark.enabled
gitCommitGuard.benchmark.tagApiUrl
gitCommitGuard.benchmark.tagResponsePath
gitCommitGuard.benchmark.tagNameField
gitCommitGuard.benchmark.tagRequestHeaders

也可以直接写进 settings.json：

{
  "gitCommitGuard.types": ["feat", "fix", "docs", "chore"],
  "gitCommitGuard.requireScope": true,
  "gitCommitGuard.requireIssue": false,
  "gitCommitGuard.issuePrefixes": ["Refs", "Closes"],
  "gitCommitGuard.subjectMinLength": 10,
  "gitCommitGuard.subjectMaxLength": 80,
  "gitCommitGuard.maxHeaderLength": 120,
  "gitCommitGuard.benchmark.enabled": true,
  "gitCommitGuard.benchmark.tagApiUrl": "https://example.com/api/benchmark/tags",
  "gitCommitGuard.benchmark.tagResponsePath": "data.tags",
  "gitCommitGuard.benchmark.tagNameField": "name",
  "gitCommitGuard.benchmark.tagRequestHeaders": {
    "Authorization": "Bearer <token>"
  }
}

说明：gitCommitGuard.issuePrefixes 不是必填项，只有在 gitCommitGuard.requireIssue 为 true 且你想自定义前缀时才需要配置。

这些扩展设置会优先于仓库里的 .git-commit-guard.json。

发布到 VS Code Marketplace 前需要修改

发布前请先修改 package.json 中这两个字段：

publisher
repository.url

Git Commit Guard

jasmine tang