mcpField
C
conventional-git

conventional-git

github.com/samber开发2414.8k 次安装4 周前更新
代码仓库

关于 conventional-git

用于规范分支名、提交信息和本地 Git worktree 的 Conventional Commits 指南，帮助贡献者保持变更历史与问题追踪的一致性。

主要功能

  1. 01Conventional 分支命名
  2. 02提交格式与类型指南
  3. 03通过页脚关闭问题
  4. 04本地 worktree 命名与清理
  5. 05Squash merge 标题规范

适用场景

  1. 01为带问题编号的功能命名分支
  2. 02编写标记破坏性变更的提交
  3. 03通过提交页脚关闭跟踪的问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/samber/cc-skills --skill conventional-git

安装后在 Claude Code 中输入/conventional-git确认已加载。

附带文件evals/evals.json

详细介绍

Conventional Commits 与分支命名

分支名称和提交消息均遵循 Conventional Commits v1.0.0——统一的命名方式可让工具自动生成变更日志、强制执行 SemVer 版本递增，并按关注点筛选历史记录。

分支命名

格式：<type>/[issue-]<description>——使用小写字母，只能用连字符，不得包含 / 以外的特殊字符。

feat/user-authentication
feat/42-user-authentication
fix/login-race-condition
fix/87-login-race-condition
docs/api-reference-update
refactor/payment-module

如果有 issue 编号，请将其作为前缀——GitHub 和 GitLab 会自动创建链接，也便于通过 git log 立即追溯到跟踪器。描述保持在 50 个字符以内——大多数 git UI 会在列表中截断超出此长度的分支名称。根据所做的工作选择对应类型——读者会依据这一约定快速了解分支用途。

分支名称中绝对不要包含 worktree——git worktree 是本地检出机制，而不是分支概念；使用该名称会将实现细节暴露到远程端，并让其他贡献者困惑。

Worktree 命名

Worktree 是本地检出目录——不会出现在远程端。将其放在 .claude/worktrees/ 下，并将分支名称中的 / 分隔符替换为 - 来命名。

git worktree add .claude/worktrees/feat-user-authentication feat/user-authentication
git worktree add .claude/worktrees/fix-87-login-race-condition fix/87-login-race-condition

目录名称与分支名称保持一致，这样 git worktree list 的输出更易读，也无需检查检出内容，就能立即追溯每个 worktree 对应的分支。创建新 worktree 前先运行 git worktree list——如果已有 worktree 对应同一分支，就重复使用。

每个 worktree 只用于一个分支。在其他人的 worktree 中处理无关工作，会让变更归属变得模糊，也更容易在清理时出错。

分支合并后移除 worktree——无论是在本地合并后，还是在远程端的拉取请求／合并请求关闭后。过时的 worktree 会不断累积，让 git worktree list 难以阅读。

git worktree remove .claude/worktrees/feat-user-authentication   # branch merged locally
git worktree prune                                                # remove refs to already-deleted directories

提交消息格式

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

类型：

TypeSemVer适用场景
featMINOR新功能
fixPATCH修复错误
docs—仅文档
style—格式调整，不改变逻辑
refactor—重构，不涉及新功能或修复
perf—性能改进
test—添加或修复测试
build—构建系统、依赖项
ci—CI 配置
chore—其他事项（非 src/test）
revert—撤销之前的提交

规则：

  • 主题行不超过 72 个字符——git log 和 GitHub/GitLab UI 会静默截断更长的主题行
  • 使用祈使语气：“add”而不是“added”——读起来像指令，而不是历史记录
  • 不使用大写字母，末尾不加句号——确保变更日志工具能够统一解析
  • 正文与主题之间空一行——解析器会在第一个空行处分割标题和正文
  • 破坏性变更：在类型／范围后使用 !，或添加 BREAKING CHANGE: 页脚（触发 MAJOR 版本递增）——仅在正文中描述，变更日志工具无法识别
  • revert 提交 SHOULD 在正文中包含 This reverts commit <hash>.——git revert 会自动生成此内容；不要删除
  • 绝对不要在提交中添加 Claude 签名、AI Agent 署名，或 Claude 或任何其他 AI Agent 的 Co-authored-by 尾注

示例：

feat(auth): add JWT token refresh

fix: prevent race condition on concurrent requests

Introduce request ID and reference to latest request.
Dismiss responses from stale requests.

refactor!: drop support for Go 1.18

BREAKING CHANGE: Go 1.18 no longer supported; uses stdlib APIs from 1.21+

通过提交消息关闭议题

GitHub 和 GitLab 都会检测提交消息中的关键词，并在提交合并到默认分支时自动关闭所引用的议题。请将引用放在页脚中（推荐，这样可以保持主题行简洁）。

关键词： close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved——不区分大小写。

GitHub：

fix(auth): prevent token expiry race condition

Closes #42
Closes owner/repo#99
  • 合并到默认分支时触发（通常是 main）
  • 跨仓库：Closes owner/repo#42
  • 关闭多个议题：Closes #42, closes #43
  • 也适用于 PR 描述

GitLab：

feat: add dark mode support

Resolves #101
Closes group/project#42
  • 合并到默认分支时触发（可在每个项目中配置）
  • 跨项目：Closes group/project#42
  • 关闭多个议题：Closes #101, closes #102
  • 也适用于 MR 描述

提示： 将提交类型与关闭议题的操作对应起来——例如用 fix: 关闭错误议题，用 feat: 关闭功能请求——可使变更日志在语义上保持连贯。

常见错误

错误修正
feat: Added login pagefeat: add login page——使用祈使语气，不要大写
fix: fix bug.fix: fix bug——末尾不要加句号
主题超过 72 个字符缩短主题；将详细信息移至正文
只在正文中说明不兼容变更添加 ! 或 BREAKING CHANGE: 页脚——工具无法检测仅写在正文中的内容
feat(adding-auth): ...feat(auth): ...——范围应为名词，而不是动词
在主题行中写 Closes #42移至页脚——保持主题简洁且易于解析

最佳实践

  • 让分支类型与提交类型保持一致——feat/auth-* 分支对应 feat(auth): 提交
  • 每个分支只处理一个关注点——在功能分支中混入修复会使变更日志含义不清
  • 在分支内统一使用范围——始终使用 feat(auth):，不要中途改为 feat(user):
  • 压缩合并： 压缩合并 PR/MR 时，分支提交会合并为一个提交，PR/MR 标题会成为提交消息。如果标题不符合 Conventional Commits 格式，变更日志生成会悄无声息地出错。压缩合并前务必设置 PR 标题。

评论

支持 Markdown