1. 项目概述与核心价值最近在整理团队代码仓库时发现一个挺普遍的问题提交记录五花八门什么“fix bug”、“update”、“test”之类的信息满天飞。这种混乱的提交历史不仅让后续的代码审查和问题追溯变得异常困难也让自动化工具比如生成变更日志几乎无法正常工作。这让我意识到一个清晰、规范的提交信息远不止是“好看”那么简单它直接关系到团队的协作效率和项目的长期可维护性。于是我花了一些时间把个人和团队实践中沉淀下来的一套“干净提交”方法论整理成了一个名为clean-commit-skill的项目。这个项目不是一个新发明的工具而是一套集成了最佳实践、自动化脚本和团队规范的操作指南与技能包旨在帮助开发者无论是新手还是老鸟都能快速掌握并产出高质量的 Git 提交信息。clean-commit-skill的核心目标很明确将提交信息从随意的“注释”提升为有价值的“文档”。它解决的不仅仅是格式问题更是思维习惯和团队协作规范的问题。通过这套方法每一次提交都能清晰地回答三个问题这次改动的范围是什么类型改动的核心内容是什么主题以及为什么需要这个改动正文与脚注对于任何使用 Git 进行版本控制的团队或个人开发者尤其是那些追求工程卓越、重视代码历史和自动化流程的团队掌握这项技能都至关重要。接下来我就把这套方法的里里外外、从理念到实操毫无保留地拆解一遍。2. 提交规范的核心Conventional Commits 深度解析2.1 规范的价值与选择为什么是 Conventional Commits约定式提交在开源世界和众多企业内部它已经成为事实上的标准比如 Angular、Vue.js 等知名项目都在使用。它的魅力在于其极简的语义化和强大的可扩展性。这套规范通过一个简单的模板type(scope): subject为提交信息赋予了机器可读的结构。这意味着我们可以编写脚本自动解析提交历史根据type类型自动生成变更日志CHANGELOG根据BREAKING CHANGE破坏性变更标识自动决定版本号遵循语义化版本 SemVer。对于开发者而言它强制我们思考每次提交的“意图”是修复缺陷、新增功能还是重构代码这种思考能有效减少“大杂烩”式的提交让每次提交保持单一职责。注意选择 Conventional Commits 并非排斥其他规范但其生态最成熟工具支持最广泛如 commitlint, standard-version对于大多数团队来说是性价比最高的选择。2.2 类型Type的实战定义与边界规范文档给出了一些基础类型如feat,fix但在实际项目中我们需要根据自身工作流进行更精细的定义。以下是我们团队在clean-commit-skill中扩展和明确定义的类型列表这比通用规范更具指导性feat新增功能。这是最明确的类型对应着用户可见的新能力或 API。关键在于“新增”而不是修改现有功能的行为。如果某个修改导致了新功能的产生但主要目的是修复则应归为fix。fix修复缺陷。针对的是代码中错误的、不符合预期行为的修正。这里有个常见误区修复拼写错误或注释算不算我们的原则是如果错误影响了运行时行为或公开 API 文档算fix如果只是源码内的拼写建议用chore或docs。docs文档更新。仅限对README.md、API 文档、代码注释如果注释是文档的一部分如 JSDoc的修改。修改项目中的.md文件但非文档如修改配置说明不算。style代码风格调整。指不影响代码运行结果的修改例如空格、缩进、分号、引号等格式化问题。特别注意这与 CSS 样式无关。很多前端同学容易混淆。refactor代码重构。即在既不修复错误也不增加功能的前提下优化代码结构、提高可读性、性能微调非算法级重大提升。如果重构的同时修复了隐含的 bug应以fix为主。perf性能优化。明确以提高性能为目的的代码更改例如算法优化、引入缓存、减少不必要的计算或 I/O 操作。需要与refactor区分refactor可能附带性能提升但主要目的是结构优化perf的主要和直接目的就是提升性能。test测试相关。增加或修改测试用例单元测试、集成测试。修复测试代码中的错误也用此类型。chore构建过程或辅助工具的变动。更新构建脚本Webpack, Gulp、依赖管理package.json中非feat/fix的版本更新、CI 配置等。这是一个“杂物筐”但应谨慎使用避免掩盖重要变更。ci持续集成相关。专门针对.github/workflows、.gitlab-ci.yml、Jenkinsfile 等 CI/CD 配置文件的修改。与chore分离是为了更清晰地追踪自动化流程的变化。2.3 范围Scope的界定与粒度控制范围Scope是可选的用于说明提交影响的具体模块或领域。它的设置需要平衡清晰度和灵活性。范围太泛如feat(project):失去意义太细如feat(login-button-color):则维护成本高。我们的经验是基于目录结构对于 Monorepo范围可以是子包名packages/core。对于普通项目可以是顶层目录名如user,order,auth。基于功能模块如cart购物车、payment支付、notification通知。特殊范围*或global表示影响多个模块或难以归类。deps专门用于依赖升级chore(deps): bump axios from 1.3.4 to 1.6.2。约定大于配置团队应在项目初期约定一个范围列表并记录在CONTRIBUTING.md中。当出现新的模块时及时补充。2.4 主题Subject的写作精髓主题行是提交信息的“标题”必须在 50 个字符以内精炼地概括本次提交。好的主题遵循以下原则使用祈使句现在时态仿佛在命令代码库进行此次变更。例如“add user authentication middleware” 而不是 “added ...” 或 “adding ...”。首字母小写规范要求无需句号结尾。具体而非抽象避免 “update code” 或 “fix stuff”。应写为 “fix incorrect response status for 404 errors” 或 “feat(user): add password reset via email”。直接关联类型与范围如果类型和范围已经清晰主题应直接描述“做了什么”无需重复类型信息。例如fix(api): handle null pointer in user serializer就很好而fix(api): fix null pointer bug则略显冗余。3. 提交信息的完整结构与正文撰写3.1 正文Body3. 提交信息的完整结构与正文撰写3.1 正文Body解释“为什么”与“如何做”主题行说明了“做了什么”正文则要深入解释“为什么做”以及“如何做的”如果改动复杂。这是提交信息最有价值的部分也是很多开发者忽略的。正文的撰写不是记流水账而是提供决策上下文。格式与内容要点与主题空一行在主题行后先空一行再开始写正文。每行72字符换行保持可读性在终端中无需水平滚动即可阅读。使用段落复杂的改动可以用多个段落描述。第一段通常是概括性原因后续段落描述具体细节。聚焦动机与权衡解释这个变更的必要性修复了什么 issue参考了什么设计考虑了哪些替代方案及其被否决的原因。例如“这个重构是为了解决UserService中紧耦合的邮件发送逻辑它使得单元测试难以编写。我们引入了NotificationDispatcher接口将邮件、短信等通知方式解耦。考虑过使用事件总线但鉴于当前复杂度接口抽象更轻量且直接。”避免罗列代码变更Git diff 已经清晰展示了“改了哪几行”。正文不需要说“修改了foo.js的第 10-15 行”而应该说“将硬编码的 API 地址提取为环境变量以支持多环境部署”。引用问题追踪如果对应 JIRA、GitHub Issue 等应在正文中提及如 “Closes #123” 或 “Related to PROJ-456”。这建立了提交与项目管理的链接。3.2 脚注Footer元数据与破坏性变更脚注部分放置一些重要的元信息格式通常是KEYWORD: VALUE。核心关键词BREAKING CHANGE:这是最重要的脚注。用于标识引入了不向后兼容的 API 变更。它必须出现在脚注部分并以BREAKING CHANGE:开头后接空格和对变更的描述以及迁移指南。例如BREAKING CHANGE: getUser(id) 方法已重命名为 fetchUser(uid)。 迁移方案将所有调用 getUser() 的地方替换为 fetchUser()参数不变。在类型/主题中也可以通过添加!来标识如feat(api)!: rename getUser to fetchUser。工具会识别这两种方式。Reviewed-by:、Tested-by:在需要严格审核流程的团队中使用记录代码审查或测试人员。Signed-off-by:用于开发者原产地证书DCO在一些开源项目中要求。脚注的格式规范每个脚注条目占一行。多个脚注条目之间无空行。脚注与正文之间用一个空行分隔。3.3 一个完整的优秀示例结合以上所有要点一个完整的提交信息示例如下feat(auth): implement refresh token mechanism The previous authentication relied solely on short-lived access tokens, requiring users to log in frequently. This adds a secure refresh token flow, extending session persistence while maintaining security. - Added refreshToken field to user schema and JWT payload. - Implemented /api/auth/refresh endpoint to exchange refresh token for new access token. - Refresh tokens are stored hashed in DB and invalidated on single-use. Security considerations: - Refresh tokens are long-lived but single-use and rotated on each refresh. - They are transmitted only via secure, HTTP-only cookies. Closes #78 BREAKING CHANGE: The login response body now includes a refreshToken field (in addition to accessToken). Client-side storage logic must be updated accordingly. The new /api/auth/refresh endpoint must be integrated for seamless session renewal.这个示例中类型、范围、主题清晰正文详细说明了动机、实现要点和安全考量脚注关闭了 issue 并明确了破坏性变更信息量充足且结构完美。4. 从规范到习惯自动化工具链配置4.1 提交信息校验Commitlint知道规范是一回事每次提交都记得遵守是另一回事。Commitlint是一个用于检查提交信息格式的 Node.js 工具。它的配置非常灵活。安装与基础配置# 安装 commitlint 及其通用配置 npm install --save-dev commitlint/cli commitlint/config-conventional创建配置文件commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [ feat, fix, docs, style, refactor, perf, test, chore, ci ]], scope-case: [2, always, lower-case], subject-case: [2, never, [sentence-case, start-case, pascal-case, upper-case]], subject-max-length: [2, always, 72], body-max-line-length: [2, always, 100], }, };这里我们扩展了type-enum加入了我们自定义的ci类型并设置了一些规则如主题行不能以大写字母开头等。与 Git Hook 集成检查只有在提交时触发才有意义。我们需要用到 Git 的commit-msghook。Husky可以让我们轻松管理 Git hooks。# 安装 husky npm install --save-dev husky npx husky init然后在自动生成的.husky目录下编辑或创建commit-msg文件#!/usr/bin/env sh . $(dirname -- $0)/_/husky.sh npx --no -- commitlint --edit $1这样每次执行git commit时commitlint都会自动校验输入的提交信息格式不合格则会阻止提交。4.2 交互式提交Commitizen对于不熟悉规范或者想减少记忆负担的开发者Commitizen提供了一个命令行问答界面一步步引导你生成符合规范的提交信息。安装与适配器配置# 安装 commitizen 和 conventional-changelog 适配器 npm install --save-dev commitizen cz-conventional-changelog在package.json中配置{ config: { commitizen: { path: ./node_modules/cz-conventional-changelog } }, scripts: { commit: cz } }现在你可以运行npm run commit或npx cz来代替git commit。它会依次询问你更改的类型、影响的范围、简短的描述、详细的描述、是否有破坏性变更、是否关联 issue 等。对于团队新人这是极好的上手工具。实操心得在团队中推广时可以强制要求使用npm run commit进行提交。可以将git commit命令通过pre-commithook 进行简单拦截提示使用规范命令。4.3 自动化变更日志与版本管理standard-version规范提交的最大红利之一就是可以自动化生成美观的变更日志CHANGELOG并基于语义化版本SemVer自动升级版本号。standard-version库正是为此而生。工作流程集成# 安装 npm install --save-dev standard-version在package.json中添加脚本{ scripts: { release: standard-version, release:minor: standard-version --release-as minor, release:major: standard-version --release-as major } }当你完成一个功能开发或修复了一批 bug准备发布新版本时只需运行npm run releasestandard-version会分析自上次 tag 以来的所有提交。根据feat类型提交决定是否升级次版本号minor根据fix等决定是否升级修订号patch根据BREAKING CHANGE决定是否升级主版本号major。自动更新package.json或pyproject.toml等中的版本号。根据提交信息自动生成或更新CHANGELOG.md文件并按类型和范围归类提交。创建一个新的 Git commit 来记录这次版本发布并打上版本 tag如v1.2.0。生成的 CHANGELOG 示例# Changelog ## [1.2.0] - 2023-10-27 ### Features * **(auth):** implement refresh token mechanism (#85) ### Bug Fixes * **(api):** handle null pointer in user serializer (#91) * **(ui):** correct button color in dark mode (#87) ### BREAKING CHANGES * **(auth):** Login response now includes refreshToken. Client storage logic needs update.这彻底解放了手动维护版本和变更日志的繁琐工作且日志内容清晰、专业。5. 高级工作流与团队协作实践5.1 在 Pull Request 中保持提交清晰在基于 Git Flow 或 GitHub Flow 的协作中一个功能分支可能包含多个提交。如何保证合并到主分支时的历史清晰策略一合并时压缩Squash Merge这是最常用的策略。开发者在特性分支上可以自由提交fix: typo,feat: add component A,style: format在创建 Pull Request (PR) 后合并时选择 “Squash and merge”。GitHub/GitLab 会将这个分支的所有提交压缩成一个提交到主分支。关键在于你必须为这个压缩后的提交撰写一个高质量的、符合规范的提交信息通常这会由 PR 的标题和描述自动生成或手动修改。这个信息应该概括整个 PR 的变更。策略二本地整理后再推送对于追求更精细历史记录的项目可以在本地分支上使用git rebase -i交互式变基来整理提交历史将小的、琐碎的提交如“修正拼写”合并squash到相关的功能提交中并重写reword提交信息使得分支历史在推送到远程前就已经非常清晰。然后使用常规的合并Create a merge commit。这对开发者要求较高但能产生更干净的历史。团队规范建议在CONTRIBUTING.md中明确团队使用的合并策略。对于大多数团队“Squash Merge 精心编写的 PR 描述”是平衡了清晰度与操作复杂度的最佳实践。要求 PR 描述必须使用模板包含变更动机、测试情况、影响范围等。5.2 提交信息模板与编辑器配置你可以在项目中放置一个.gitmessage模板文件或者配置 Git 全局使用模板。创建模板文件在项目根目录创建.gitmessage# type(scope): subject # |---- 不超过50字符 ----| # # 正文解释“为什么”进行这个更改而不是“做了什么”。 # 使用祈使句现在时态。 # 每行72字符换行。 # # 脚注 # - 关联的问题 (如 Closes #123) # - 破坏性变更说明 (以 BREAKING CHANGE: 开头) # # --- 提交前请删除所有注释行--- # 可用的类型: feat, fix, docs, style, refactor, perf, test, chore, ci.然后配置 Git 使用此模板git config commit.template ./.gitmessage或者全局配置git config --global commit.template ~/.gitmessage这样每次git commit时编辑器都会预加载这个模板提醒你填写各个部分。配置默认编辑器确保你使用的是功能强大的编辑器如 VSCode, Vim, Nano来编写提交信息而不是简单的命令行输入。可以通过git config --global core.editor code --waitVSCode来设置。5.3 处理“琐碎”提交与“事后”修正总有需要提交“琐碎”更改的时候比如修改一个单词拼写。对于这类提交我们的原则是如果它属于当前正在开发的功能或修复的一部分尽量通过git commit --amend或git rebase -i合并到上一个相关提交中。如果它是一个独立的、微小的修正比如修复 README 中的链接那么使用chore或docs类型并写清楚即可例如docs: fix broken link in getting-started guide。如果发现刚刚提交的信息有误比如类型写错、描述不清可以使用git commit --amend命令来修改最近一次提交的信息。如果错误发生在更早的提交则需要使用git rebase -i进行交互式变基来重写历史。注意在已经推送到远程共享分支后重写历史是危险操作需团队协商。6. 常见问题与排查技巧实录6.1 Commitlint 校验失败怎么办当你的提交被commitlint拦截时它会给出明确的错误信息。以下是一些常见错误及解决方法错误信息可能原因解决方案type must be one of [...]使用了未定义的类型。检查commitlint.config.js中的type-enum规则确保使用的类型如ci已添加到列表中。subject may not be empty主题行为空。确保在type(scope):后填写了描述。subject must not be sentence-case主题行首字母大写。将主题行首字母改为小写。bodys lines must not be longer than 100 characters正文行超长。在编辑器中手动换行确保每行不超过100字符或你配置的长度。scope must be kebab-case范围格式错误。范围应使用小写和连字符如user-api而不是userApi或UserAPI。调试技巧你可以使用echo your message \| npx commitlint来快速测试一条提交信息是否符合规则而无需真正提交。6.2 使用 Commitizen 时卡住或报错问题运行npx cz没有出现交互界面或者报错找不到模块。排查确认node_modules中已安装commitizen和cz-conventional-changelog。检查package.json中的config.commitizen.path配置路径是否正确。如果使用全局安装的 commitizen路径可能不同。尝试直接运行./node_modules/.bin/cz。清除 npm 缓存npm cache clean --force并重新安装依赖。6.3 standard-version 不生成预期的版本号或 CHANGELOG问题运行npm run release后版本号跳变不符合预期如修复了 bug 但版本号从 1.0.0 跳到了 2.0.0。排查检查提交历史运行git log --oneline查看自上次 tag 以来的提交。确认是否有feat:或BREAKING CHANGE:提交。standard-version严格遵循 SemVer。检查上次 tag运行git describe --tags --abbrev0查看当前最新的 tag。standard-version是基于与上一个 tag 的差异来计算版本的。手动指定版本如果自动判断有误可以使用npm run release -- --release-as 1.0.1来手动指定下一个版本号。首次发布如果项目还没有任何 tagstandard-version会从1.0.0开始。你可以通过npm run release -- --first-release来生成 CHANGELOG 但不升级版本和打 tag。检查配置文件可以在package.json中配置standard-version的选项例如跳过某些文件、自定义 CHANGELOG 格式等。6.4 团队中有成员不遵守规范怎么办技术手段只能辅助不能强制。推广规范需要结合文化和流程降低门槛提供完善的工具链Commitizen和编辑器模板让遵守规范比不遵守更简单。纳入流程将规范的提交信息作为代码合并Merge Request/Pull Request的前提条件。在 PR 描述模板中强调这一点。CI 流水线可以集成commitlint检查目标分支的合并提交信息。教育与引导在团队内部分享会中讲解规范的价值展示清晰的 CHANGELOG 和自动化发布带来的效率提升。将CONTRIBUTING.md文档写得清晰易懂。温和提醒在代码审查中如果发现提交信息不规范可以温和地指出并建议修改通过git commit --amend然后git push --force-with-lease注意安全。以身作则团队负责人和技术骨干必须首先严格遵守树立榜样。6.5 处理合并冲突后的提交信息在使用git merge或git rebase解决冲突后Git 可能会自动生成一个合并提交其默认信息类似于 “Merge branch feature/x into main”。这个提交信息通常不符合规范。对于git merge可以在合并时使用--no-commit选项先暂停然后手动编写一个符合规范的提交信息再完成提交。git merge feature/x --no-commit # ... 解决任何冲突 ... git commit -m feat(scope): integrate feature X对于git rebase在变基过程中每个原始提交都会被重新应用。如果发生冲突解决后使用git rebase --continue。原始提交的信息会被保留除非你使用git rebase -i进行编辑。合并提交在变基中通常会被消除从而得到一条线性的历史这本身就更清晰。掌握clean-commit-skill的精髓本质上是在培养一种工程素养。它开始时可能需要一点额外的思考和操作但一旦形成肌肉记忆并享受到它带来的清晰历史、自动化文档和高效协作的红利你就会发现这一切都是值得的。这套技能包的价值会随着项目时间和团队规模的扩大而成倍增长。