1. 为什么提交信息值得你花心思你有没有过这种经历线上出了个bug需要定位是哪次改动引入的结果翻看提交历史满屏都是“fix bug”、“update”、“修改一下”、“提交”这类信息。你只能一个个点进去看diff运气不好翻了几十页才找到目标半小时就这么没了。更糟的是如果这个项目是半年前你自己写的你连当时为什么这么改都想不起来了。Git commit message提交信息这件事看起来是小事实际上直接影响三件事代码审查的效率、问题回溯的速度、以及团队协作的沟通成本。我见过太多项目代码写得挺漂亮但提交历史一塌糊涂导致后来接手的人怨声载道。反过来一个提交信息规范清晰的项目哪怕代码本身一般维护起来也顺手得多。这篇文章面向所有用Git做版本管理的开发者不管你是刚入行的新手还是写了几年代码的老手只要你还在往仓库里提交代码这套实践就跟你有关。我会从提交信息的结构设计、撰写规范、工具链配置、团队落地几个层面把这件事讲透并且给出可以直接抄作业的配置和模板。全文基于我这些年带团队、做代码审查、维护开源项目的实际经验不是从文档里抄来的理论。先抛一个核心观点提交信息不是写给自己看的备忘录而是写给未来的自己和同事的一封短信。你写的时候多花三十秒别人读的时候可能省下三十分钟。这笔账怎么算都划算。2. 提交信息的结构设计与核心思路拆解2.1 一条合格的提交信息长什么样先看一个反面例子这种提交信息你在很多仓库里都能见到update再看一个正面例子feat(auth): 新增手机号验证码登录方式 由于部分用户反馈忘记密码后找回流程太长增加了手机号验证码的 直接登录入口。验证码有效期为5分钟同一手机号60秒内只能请求一次。 Closes #482两者的差距一目了然。一条合格的提交信息应该包含三个层次的信息标题行Subject一句话说清楚这次提交做了什么控制在50个字符以内中文的话大约25个字让人一眼扫过去就知道大概。正文Body解释为什么这么改而不是重复标题说改了什么。正文可以分多段每段说明一个点。脚注Footer关联的issue编号、破坏性变更说明、共同作者等元信息。这个结构不是我拍脑袋定的它来自Git社区的长期实践沉淀。Linux内核、Angular、Vue这些大型项目的提交历史基本都是这个套路。为什么是三层而不是一层因为不同的人读提交信息的场景不一样快速浏览的人只看标题做代码审查的人看正文做发布管理的人看脚注。三层结构让每类人都能快速找到自己需要的信息。2.2 为什么标题行要限制长度标题行限制在50个字符左右这个数字有讲究。Git命令行默认的显示宽度、GitHub的提交列表、各种Git客户端的日志视图基本都在50到72个字符之间截断。超过这个长度标题就会被省略号截掉读者反而看不到关键信息。我个人的习惯是标题行尽量控制在40个中文字符以内因为中文一个字符占两个英文字符的宽度。如果你用英文写提交信息那就控制在50个英文字符。写完之后自己数一下超了就精简。这里有个实操技巧标题行不要以句号结尾。这是英文提交信息的惯例中文也适用。因为标题本身就是一个短语或短句不是完整段落加句号显得多余。另外标题行的首字母大小写、动词形式团队内部要统一不要一会儿“新增”一会儿“Added”一会儿“add”。2.3 正文为什么强调“为什么”而不是“做了什么”这是很多人容易搞混的地方。标题已经说了“做了什么”正文如果还在重复“做了什么”那就是浪费空间。正文的价值在于回答为什么要做这个改动当时的背景是什么有没有考虑过其他方案举个例子。假设你把某个接口的超时时间从3秒改成了10秒。标题写“调整接口超时时间”就够了。正文应该写“近期监控发现该接口在高峰期响应时间经常超过3秒导致大量请求失败。经过排查是下游服务在批量处理时耗时较长。暂时将超时调整为10秒作为过渡方案后续计划推动下游做异步化改造。” 这段正文里包含了问题现象、排查结论、临时方案、后续计划这些信息在diff里是看不出来的但对后来的人极其有价值。我踩过的一个坑早期写提交信息只写“修复登录问题”结果三个月后同样的登录问题又出现了我翻到那次提交完全想不起来当时修的是什么、怎么修的只能重新排查一遍。从那以后我就养成了在正文里写清楚背景和思路的习惯。2.4 约定式提交让机器也能读懂你的提交约定式提交Conventional Commits是目前最流行的一套提交信息规范。它的核心是在标题行加一个类型前缀格式是类型(范围): 描述常见的类型有这些类型含义使用场景feat新功能增加了用户可见的新能力fix修复缺陷修了一个bugdocs文档变更只改了文档没动代码style格式调整空格、分号、缩进不影响逻辑refactor重构既不是新功能也不是修bug的代码调整perf性能优化提升了运行效率test测试相关增加或修改测试用例chore杂项构建流程、依赖更新等范围scope是可选的用来标明改动影响的范围比如feat(auth)、fix(api)、docs(readme)。这套规范最大的好处是可自动化。有了类型前缀工具可以自动生成变更日志changelog、自动判断版本号该升major还是minor还是patch。比如用了standard-version这类工具你提交的时候按规范写发版的时候一条命令就能生成完整的CHANGELOG.md省去手工整理的麻烦。提示约定式提交不是强制标准小团队或者个人项目不一定要全套照搬。但类型前缀这个习惯我强烈建议养成哪怕你只用一个简单的“feat/fix/docs”三分法也比什么都不加强。3. 核心细节解析与实操要点3.1 标题行的动词选择与语态标题行用什么动词直接决定了提交信息的可读性。我总结了一个简单的原则用祈使句不用过去式不用进行时。对比一下差Added user login feature过去式差Adding user login feature进行时好add user login feature祈使句好新增用户登录功能中文祈使句为什么用祈使句因为Git本身生成的信息就是祈使句比如Merge branch xxx、Revert xxx。你的提交信息和Git自动生成的信息风格一致整个历史读起来才顺畅。想象一下你在给代码库下命令“添加这个功能”、“修复那个bug”读起来干脆利落。中文提交信息在这方面反而有优势因为中文动词没有时态变化“新增”、“修复”、“调整”这些词天然就是祈使语气不用纠结时态问题。3.2 正文的换行与格式正文的换行有个硬性要求每行不要超过72个字符。这是因为Git在终端里显示提交信息时超过72个字符会自动换行如果你的原文没有在合适的位置断行显示出来就会乱七八糟。用命令行提交的时候可以这样操作git commit不带-m参数Git会打开默认编辑器你就可以写多行提交信息了。第一行写标题空一行然后写正文。编辑器里通常会有注释提示你每行不要超过72字符。如果你习惯用-m参数也可以写多行git commit -m feat(auth): 新增手机号验证码登录 -m 由于部分用户反馈忘记密码后找回流程太长增加了手机号验证码的直接登录入口。两个-m参数之间会自动加一个空行第一个是标题第二个是正文。但正文如果有多段这种方式就不太方便了还是推荐用编辑器。3.3 脚注的写法与关联issue脚注部分用来放元信息最常见的几种Closes #123或Fixes #123表示这次提交关闭了某个issue。GitHub、GitLab这些平台会自动识别这个关键词合并后自动关闭对应issue。BREAKING CHANGE: xxx表示这次提交包含破坏性变更升级时需要注意。Co-authored-by: 某某 email表示共同作者。这里有个细节Closes和Fixes后面跟的issue编号必须是同一仓库的issue。如果是跨仓库关联需要写完整路径比如Closes owner/repo#123。注意BREAKING CHANGE必须大写而且后面要跟冒号。这是约定式提交规范里明确定义的工具靠这个关键词来识别破坏性变更。写成breaking change或者Breaking Change都可能识别不到。3.4 什么算“一次提交”粒度怎么把握提交粒度是另一个容易被忽视的点。我见过有人一天的工作攒成一个提交标题写“今日工作”也见过有人改一行就提交一次历史里几百个提交全是“修改”。合理的粒度原则是一个提交只做一件事且这件事是完整的。具体来说一个提交应该能独立通过代码审查不依赖后续提交才能理解。一个提交不应该混合多个不相关的改动。比如你修了一个bug顺手格式化了整个文件这两件事应该分成两个提交。一个提交应该是可回滚的。如果这个提交出了问题需要撤销撤销它不应该影响其他功能。为什么粒度这么重要因为代码审查和问题定位都是以提交为单位的。如果一个提交里混了五件事审查的人很难逐项确认如果出了问题需要回滚你没法只回滚其中一件事。实操中我推荐用git add -p来分块暂存。这个命令会让你逐块确认要暂存哪些改动这样你就可以把一次编辑中的多个改动拆成多个提交。刚开始可能觉得麻烦用习惯了会发现这是保持提交历史干净的最有效手段。3.5 提交信息里的语言选择团队用中文还是英文写提交信息这个没有绝对的对错但必须统一。我见过最糟糕的情况是同一个仓库里有人写中文有人写英文有人中英混杂读起来非常割裂。如果团队都是中文母语者且项目不涉及外部协作用中文完全没问题。如果项目是开源的或者团队有非中文母语的成员那建议用英文。混合团队的情况下英文是更安全的选择。不管选哪种语言专有名词、技术术语保持原文。比如“API”、“token”、“cache”这些词不要硬翻译成“接口”、“令牌”、“缓存”因为大家在日常沟通中本来就说英文翻译过来反而增加理解成本。4. 实操过程与核心环节实现4.1 配置提交模板让规范落地光靠自觉是不够的人总有偷懒的时候。最有效的办法是配置一个提交模板每次git commit的时候自动带出格式提示。在项目根目录创建一个.gitmessage文件# 类型(范围): 标题 # 类型可选feat / fix / docs / style / refactor / perf / test / chore # 标题不超过50个字符不以句号结尾 # 空一行后写正文说明为什么这么改每行不超过72字符 # 空一行后写脚注如 Closes #123然后配置Git使用这个模板git config commit.template .gitmessage如果想让这个配置对团队所有人生效可以把.gitmessage提交到仓库里然后在项目的README或者贡献指南里说明需要执行上面这条命令。更彻底的做法是用core.hooksPath配置一个commit-msg钩子在提交时自动校验格式不符合规范就拒绝提交。4.2 用commitlint做自动校验commitlint是一个专门用来校验提交信息格式的工具。配合huskyGit钩子管理工具可以在每次提交时自动检查。安装步骤npm install --save-dev commitlint/cli commitlint/config-conventional husky创建commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [ feat, fix, docs, style, refactor, perf, test, chore ]], subject-max-length: [2, always, 50], body-max-line-length: [2, always, 72] } };初始化husky并添加钩子npx husky install npx husky add .husky/commit-msg npx --no -- commitlint --edit $1配置好之后如果你提交的信息不符合规范会被直接拒绝并提示具体哪里有问题。这个机制对团队新人特别有用能帮他们快速养成习惯。提示commitlint的规则可以按团队情况调整。比如你们不用约定式提交可以把type-enum规则关掉只保留长度校验。工具是为人服务的不要被工具绑架。4.3 用交互式工具辅助撰写如果你觉得手写提交信息太麻烦可以试试commitizen。它提供一个交互式命令行界面一步步问你这次改动的类型、范围、描述、关联issue最后自动拼出规范的提交信息。安装npm install --save-dev commitizen cz-conventional-changelog npx commitizen init cz-conventional-changelog --save-dev --save-exact之后用npx cz代替git commit就会进入交互式问答。这种方式对新手特别友好不需要记格式跟着提示走就行。不过我个人在熟练之后就不太用commitizen了因为交互式问答有时候比直接写还慢。我的习惯是配好模板和校验然后直接git commit手写。工具的选择看个人习惯没有标准答案。4.4 从提交历史自动生成变更日志规范提交信息的一个直接回报就是可以自动生成CHANGELOG。用standard-version这个工具npm install --save-dev standard-version在package.json里加一个脚本{ scripts: { release: standard-version } }执行npm run release它会自动分析自上次发版以来的所有提交根据类型判断版本号该升多少feat升minorfix升patchBREAKING CHANGE升major然后生成CHANGELOG.md打上tag。这个流程的前提就是你的提交信息必须规范。如果提交信息乱七八糟生成的CHANGELOG也没法看。所以你看规范提交信息不只是为了好看它直接支撑了自动化发版流程。4.5 修改最近一次提交信息有时候提交完才发现信息写错了或者漏了关联issue。用这个命令修改最近一次提交git commit --amend这会打开编辑器让你修改最近一次提交的信息。如果只是想改信息不想改内容直接保存退出就行。注意如果这次提交已经推送到远程仓库amend之后需要强制推送这在多人协作的分支上要谨慎操作。如果要修改更早的提交信息就需要用交互式rebasegit rebase -i HEAD~3把要修改的那次提交前面的pick改成reword保存后会依次让你修改这些提交的信息。这个操作同样会改写历史只建议在未推送的本地提交上使用。5. 常见问题与排查技巧实录5.1 提交信息写错了怎么办这是最高频的问题。分几种情况场景处理方法注意事项刚提交未推送git commit --amend直接改无风险已推送但只有自己用这个分支git commit --amend后强制推送确认没有其他人基于这个分支工作已推送多人共用分支不要amend追加一次新提交说明改写公共历史会造成其他人冲突历史中较早的提交git rebase -i用 reword仅限未推送的本地提交我踩过的一个坑有一次在团队共享的分支上amend了已推送的提交然后强制推送结果同事本地拉取时产生了大量冲突花了半天才理顺。从那以后我就定了个规矩公共分支上的提交信息写错了宁可追加一条“修正上次提交信息”的提交也不改写历史。5.2 提交信息太长被截断前面说过标题行控制在50字符以内。如果你发现标题被截断了说明写太长了。解决办法是把细节移到正文里标题只保留最核心的信息。比如“修复了用户在使用手机号登录时因为验证码过期导致无法登录的问题”这个标题太长了。可以改成“fix(auth): 修复验证码过期导致的登录失败”具体细节放正文。5.3 团队新人不按规范提交这是团队落地时最常见的问题。我的经验是三道防线模板提示配置.gitmessage让新人每次提交都能看到格式要求。自动校验配置commitlint钩子不符合规范直接拒绝并给出明确的错误提示。代码审查在review时把提交信息也纳入审查范围信息写得不清楚就要求修改。三道防线里自动校验是最有效的。人都有惰性靠自觉不如靠工具。但工具也不能太严格否则会让人产生抵触情绪。我的建议是先严后松项目初期严格执行等大家养成习惯后可以适当放宽一些非关键规则。5.4 中文提交信息在工具里显示乱码这个问题通常出现在Windows环境下。原因是Git的默认编码和终端编码不一致。解决办法是设置git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8然后在终端里把编码也设为UTF-8。如果用的是某些老旧的Git客户端可能还需要在客户端设置里手动指定编码。5.5 如何关联多个issue一次提交关联多个issue可以在脚注里写多行Closes #123 Closes #456或者用逗号分隔Closes #123, #456但要注意不同平台对关键词的识别规则略有差异。GitHub支持Closes、Fixes、Resolves这几种写法后面跟#编号。GitLab也类似。如果你的项目同时托管在多个平台建议查一下各平台的文档确认。5.6 提交信息里能不能放表情符号技术上可以Git不限制提交信息的内容。但我的建议是谨慎使用。表情符号在不同终端、不同操作系统上的显示效果不一致有些环境可能显示成方块。而且表情符号会增加标题的字符宽度容易导致截断。如果你确实想用建议只在标题的类型前缀位置用比如用特定符号代替feat、fix这些文字。但这样会牺牲可读性不熟悉的人看不懂。我的做法是干脆不用保持纯文本兼容性最好。5.7 常见问题速查表问题现象可能原因解决方法提交被拒绝提示格式错误commitlint校验不通过按提示修改提交信息格式标题显示不全超过50字符精简标题细节移到正文正文显示混乱单行超过72字符手动在合适位置换行关联issue没自动关闭关键词拼写错误或格式不对检查是否用了Closes/Fixes #编号中文显示乱码编码设置不一致设置i18n.commitEncoding为utf-8amend后推送被拒绝远程有新的提交先pull --rebase再推送钩子不生效husky未正确初始化重新执行husky install6. 团队落地与长期维护的经验6.1 规范要写进贡献指南提交信息规范不能只停留在口头必须写进项目的CONTRIBUTING.md里。内容要包括格式要求、类型列表、标题长度限制、正文写法、脚注关键词。最好再配几个正例和反例让人一看就懂。贡献指南里的规范要简洁不要写成一篇论文。新人没耐心读长文把最核心的规则用列表列出来就行。详细的解释可以放在单独的文档里需要的时候再查。6.2 代码审查时把提交信息纳入检查项代码审查不只是看代码提交信息也是审查对象。我在review的时候如果看到提交信息写得不清楚会直接留言要求修改。这不是吹毛求疵而是因为提交信息是代码库的长期资产它的质量直接影响项目的可维护性。审查提交信息主要看几点标题是否清晰、正文是否解释了原因、是否关联了issue、粒度是否合理。如果一次提交里混了多个不相关的改动我会要求拆分。6.3 定期整理提交历史项目运行一段时间后提交历史可能会变得杂乱。如果项目还没发布正式版本可以考虑用rebase整理历史把零散的提交合并成有意义的单元。但如果已经发布过版本就不要动历史了因为已经有人可能基于这些提交做了工作。整理历史的原则是只整理未推送的本地提交已推送的公共历史不动。这是铁律违反它会给团队带来麻烦。6.4 工具链的维护commitlint、husky这些工具会随着版本更新而变化配置方式也可能调整。建议在项目里锁定版本号避免因为工具升级导致钩子失效。同时在CI流程里也加一道提交信息校验作为本地钩子的补充。因为本地钩子可以被绕过git commit --no-verifyCI上的校验才是最后一道防线。CI里校验提交信息的思路是在流水线里加一个步骤检查最近一次提交的信息是否符合规范。如果不符合直接让流水线失败。这样即使有人绕过了本地钩子也过不了CI这一关。6.5 我个人的一些习惯最后分享几个我自己的习惯不一定适合所有人但可以参考提交前先git diff --staged看一眼确认暂存的内容和提交信息描述的一致。标题写完后默读一遍如果读起来别扭说明没写清楚。正文里多写“因为”、“所以”、“但是”这些连接词能帮你把逻辑讲清楚。关联issue用Closes而不是Fixed因为Closes更通用GitHub和GitLab都认。破坏性变更一定要在脚注里用BREAKING CHANGE:标明这关系到版本号自动升级的正确性。这套实践我用了好几年带过几个团队落地效果是实打实的。代码审查时间缩短了问题回溯速度快了发版流程也自动化了。投入的成本就是每次提交多花三十秒回报却是长期的。这笔账怎么算都值。
1. 为什么提交信息值得你花心思你有没有过这种经历线上出了个bug需要定位是哪次改动引入的结果翻看提交历史满屏都是“fix bug”、“update”、“修改一下”、“提交”这类信息。你只能一个个点进去看diff运气不好翻了几十页才找到目标半小时就这么没了。更糟的是如果这个项目是半年前你自己写的你连当时为什么这么改都想不起来了。Git commit message提交信息这件事看起来是小事实际上直接影响三件事代码审查的效率、问题回溯的速度、以及团队协作的沟通成本。我见过太多项目代码写得挺漂亮但提交历史一塌糊涂导致后来接手的人怨声载道。反过来一个提交信息规范清晰的项目哪怕代码本身一般维护起来也顺手得多。这篇文章面向所有用Git做版本管理的开发者不管你是刚入行的新手还是写了几年代码的老手只要你还在往仓库里提交代码这套实践就跟你有关。我会从提交信息的结构设计、撰写规范、工具链配置、团队落地几个层面把这件事讲透并且给出可以直接抄作业的配置和模板。全文基于我这些年带团队、做代码审查、维护开源项目的实际经验不是从文档里抄来的理论。先抛一个核心观点提交信息不是写给自己看的备忘录而是写给未来的自己和同事的一封短信。你写的时候多花三十秒别人读的时候可能省下三十分钟。这笔账怎么算都划算。2. 提交信息的结构设计与核心思路拆解2.1 一条合格的提交信息长什么样先看一个反面例子这种提交信息你在很多仓库里都能见到update再看一个正面例子feat(auth): 新增手机号验证码登录方式 由于部分用户反馈忘记密码后找回流程太长增加了手机号验证码的 直接登录入口。验证码有效期为5分钟同一手机号60秒内只能请求一次。 Closes #482两者的差距一目了然。一条合格的提交信息应该包含三个层次的信息标题行Subject一句话说清楚这次提交做了什么控制在50个字符以内中文的话大约25个字让人一眼扫过去就知道大概。正文Body解释为什么这么改而不是重复标题说改了什么。正文可以分多段每段说明一个点。脚注Footer关联的issue编号、破坏性变更说明、共同作者等元信息。这个结构不是我拍脑袋定的它来自Git社区的长期实践沉淀。Linux内核、Angular、Vue这些大型项目的提交历史基本都是这个套路。为什么是三层而不是一层因为不同的人读提交信息的场景不一样快速浏览的人只看标题做代码审查的人看正文做发布管理的人看脚注。三层结构让每类人都能快速找到自己需要的信息。2.2 为什么标题行要限制长度标题行限制在50个字符左右这个数字有讲究。Git命令行默认的显示宽度、GitHub的提交列表、各种Git客户端的日志视图基本都在50到72个字符之间截断。超过这个长度标题就会被省略号截掉读者反而看不到关键信息。我个人的习惯是标题行尽量控制在40个中文字符以内因为中文一个字符占两个英文字符的宽度。如果你用英文写提交信息那就控制在50个英文字符。写完之后自己数一下超了就精简。这里有个实操技巧标题行不要以句号结尾。这是英文提交信息的惯例中文也适用。因为标题本身就是一个短语或短句不是完整段落加句号显得多余。另外标题行的首字母大小写、动词形式团队内部要统一不要一会儿“新增”一会儿“Added”一会儿“add”。2.3 正文为什么强调“为什么”而不是“做了什么”这是很多人容易搞混的地方。标题已经说了“做了什么”正文如果还在重复“做了什么”那就是浪费空间。正文的价值在于回答为什么要做这个改动当时的背景是什么有没有考虑过其他方案举个例子。假设你把某个接口的超时时间从3秒改成了10秒。标题写“调整接口超时时间”就够了。正文应该写“近期监控发现该接口在高峰期响应时间经常超过3秒导致大量请求失败。经过排查是下游服务在批量处理时耗时较长。暂时将超时调整为10秒作为过渡方案后续计划推动下游做异步化改造。” 这段正文里包含了问题现象、排查结论、临时方案、后续计划这些信息在diff里是看不出来的但对后来的人极其有价值。我踩过的一个坑早期写提交信息只写“修复登录问题”结果三个月后同样的登录问题又出现了我翻到那次提交完全想不起来当时修的是什么、怎么修的只能重新排查一遍。从那以后我就养成了在正文里写清楚背景和思路的习惯。2.4 约定式提交让机器也能读懂你的提交约定式提交Conventional Commits是目前最流行的一套提交信息规范。它的核心是在标题行加一个类型前缀格式是类型(范围): 描述常见的类型有这些类型含义使用场景feat新功能增加了用户可见的新能力fix修复缺陷修了一个bugdocs文档变更只改了文档没动代码style格式调整空格、分号、缩进不影响逻辑refactor重构既不是新功能也不是修bug的代码调整perf性能优化提升了运行效率test测试相关增加或修改测试用例chore杂项构建流程、依赖更新等范围scope是可选的用来标明改动影响的范围比如feat(auth)、fix(api)、docs(readme)。这套规范最大的好处是可自动化。有了类型前缀工具可以自动生成变更日志changelog、自动判断版本号该升major还是minor还是patch。比如用了standard-version这类工具你提交的时候按规范写发版的时候一条命令就能生成完整的CHANGELOG.md省去手工整理的麻烦。提示约定式提交不是强制标准小团队或者个人项目不一定要全套照搬。但类型前缀这个习惯我强烈建议养成哪怕你只用一个简单的“feat/fix/docs”三分法也比什么都不加强。3. 核心细节解析与实操要点3.1 标题行的动词选择与语态标题行用什么动词直接决定了提交信息的可读性。我总结了一个简单的原则用祈使句不用过去式不用进行时。对比一下差Added user login feature过去式差Adding user login feature进行时好add user login feature祈使句好新增用户登录功能中文祈使句为什么用祈使句因为Git本身生成的信息就是祈使句比如Merge branch xxx、Revert xxx。你的提交信息和Git自动生成的信息风格一致整个历史读起来才顺畅。想象一下你在给代码库下命令“添加这个功能”、“修复那个bug”读起来干脆利落。中文提交信息在这方面反而有优势因为中文动词没有时态变化“新增”、“修复”、“调整”这些词天然就是祈使语气不用纠结时态问题。3.2 正文的换行与格式正文的换行有个硬性要求每行不要超过72个字符。这是因为Git在终端里显示提交信息时超过72个字符会自动换行如果你的原文没有在合适的位置断行显示出来就会乱七八糟。用命令行提交的时候可以这样操作git commit不带-m参数Git会打开默认编辑器你就可以写多行提交信息了。第一行写标题空一行然后写正文。编辑器里通常会有注释提示你每行不要超过72字符。如果你习惯用-m参数也可以写多行git commit -m feat(auth): 新增手机号验证码登录 -m 由于部分用户反馈忘记密码后找回流程太长增加了手机号验证码的直接登录入口。两个-m参数之间会自动加一个空行第一个是标题第二个是正文。但正文如果有多段这种方式就不太方便了还是推荐用编辑器。3.3 脚注的写法与关联issue脚注部分用来放元信息最常见的几种Closes #123或Fixes #123表示这次提交关闭了某个issue。GitHub、GitLab这些平台会自动识别这个关键词合并后自动关闭对应issue。BREAKING CHANGE: xxx表示这次提交包含破坏性变更升级时需要注意。Co-authored-by: 某某 email表示共同作者。这里有个细节Closes和Fixes后面跟的issue编号必须是同一仓库的issue。如果是跨仓库关联需要写完整路径比如Closes owner/repo#123。注意BREAKING CHANGE必须大写而且后面要跟冒号。这是约定式提交规范里明确定义的工具靠这个关键词来识别破坏性变更。写成breaking change或者Breaking Change都可能识别不到。3.4 什么算“一次提交”粒度怎么把握提交粒度是另一个容易被忽视的点。我见过有人一天的工作攒成一个提交标题写“今日工作”也见过有人改一行就提交一次历史里几百个提交全是“修改”。合理的粒度原则是一个提交只做一件事且这件事是完整的。具体来说一个提交应该能独立通过代码审查不依赖后续提交才能理解。一个提交不应该混合多个不相关的改动。比如你修了一个bug顺手格式化了整个文件这两件事应该分成两个提交。一个提交应该是可回滚的。如果这个提交出了问题需要撤销撤销它不应该影响其他功能。为什么粒度这么重要因为代码审查和问题定位都是以提交为单位的。如果一个提交里混了五件事审查的人很难逐项确认如果出了问题需要回滚你没法只回滚其中一件事。实操中我推荐用git add -p来分块暂存。这个命令会让你逐块确认要暂存哪些改动这样你就可以把一次编辑中的多个改动拆成多个提交。刚开始可能觉得麻烦用习惯了会发现这是保持提交历史干净的最有效手段。3.5 提交信息里的语言选择团队用中文还是英文写提交信息这个没有绝对的对错但必须统一。我见过最糟糕的情况是同一个仓库里有人写中文有人写英文有人中英混杂读起来非常割裂。如果团队都是中文母语者且项目不涉及外部协作用中文完全没问题。如果项目是开源的或者团队有非中文母语的成员那建议用英文。混合团队的情况下英文是更安全的选择。不管选哪种语言专有名词、技术术语保持原文。比如“API”、“token”、“cache”这些词不要硬翻译成“接口”、“令牌”、“缓存”因为大家在日常沟通中本来就说英文翻译过来反而增加理解成本。4. 实操过程与核心环节实现4.1 配置提交模板让规范落地光靠自觉是不够的人总有偷懒的时候。最有效的办法是配置一个提交模板每次git commit的时候自动带出格式提示。在项目根目录创建一个.gitmessage文件# 类型(范围): 标题 # 类型可选feat / fix / docs / style / refactor / perf / test / chore # 标题不超过50个字符不以句号结尾 # 空一行后写正文说明为什么这么改每行不超过72字符 # 空一行后写脚注如 Closes #123然后配置Git使用这个模板git config commit.template .gitmessage如果想让这个配置对团队所有人生效可以把.gitmessage提交到仓库里然后在项目的README或者贡献指南里说明需要执行上面这条命令。更彻底的做法是用core.hooksPath配置一个commit-msg钩子在提交时自动校验格式不符合规范就拒绝提交。4.2 用commitlint做自动校验commitlint是一个专门用来校验提交信息格式的工具。配合huskyGit钩子管理工具可以在每次提交时自动检查。安装步骤npm install --save-dev commitlint/cli commitlint/config-conventional husky创建commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [ feat, fix, docs, style, refactor, perf, test, chore ]], subject-max-length: [2, always, 50], body-max-line-length: [2, always, 72] } };初始化husky并添加钩子npx husky install npx husky add .husky/commit-msg npx --no -- commitlint --edit $1配置好之后如果你提交的信息不符合规范会被直接拒绝并提示具体哪里有问题。这个机制对团队新人特别有用能帮他们快速养成习惯。提示commitlint的规则可以按团队情况调整。比如你们不用约定式提交可以把type-enum规则关掉只保留长度校验。工具是为人服务的不要被工具绑架。4.3 用交互式工具辅助撰写如果你觉得手写提交信息太麻烦可以试试commitizen。它提供一个交互式命令行界面一步步问你这次改动的类型、范围、描述、关联issue最后自动拼出规范的提交信息。安装npm install --save-dev commitizen cz-conventional-changelog npx commitizen init cz-conventional-changelog --save-dev --save-exact之后用npx cz代替git commit就会进入交互式问答。这种方式对新手特别友好不需要记格式跟着提示走就行。不过我个人在熟练之后就不太用commitizen了因为交互式问答有时候比直接写还慢。我的习惯是配好模板和校验然后直接git commit手写。工具的选择看个人习惯没有标准答案。4.4 从提交历史自动生成变更日志规范提交信息的一个直接回报就是可以自动生成CHANGELOG。用standard-version这个工具npm install --save-dev standard-version在package.json里加一个脚本{ scripts: { release: standard-version } }执行npm run release它会自动分析自上次发版以来的所有提交根据类型判断版本号该升多少feat升minorfix升patchBREAKING CHANGE升major然后生成CHANGELOG.md打上tag。这个流程的前提就是你的提交信息必须规范。如果提交信息乱七八糟生成的CHANGELOG也没法看。所以你看规范提交信息不只是为了好看它直接支撑了自动化发版流程。4.5 修改最近一次提交信息有时候提交完才发现信息写错了或者漏了关联issue。用这个命令修改最近一次提交git commit --amend这会打开编辑器让你修改最近一次提交的信息。如果只是想改信息不想改内容直接保存退出就行。注意如果这次提交已经推送到远程仓库amend之后需要强制推送这在多人协作的分支上要谨慎操作。如果要修改更早的提交信息就需要用交互式rebasegit rebase -i HEAD~3把要修改的那次提交前面的pick改成reword保存后会依次让你修改这些提交的信息。这个操作同样会改写历史只建议在未推送的本地提交上使用。5. 常见问题与排查技巧实录5.1 提交信息写错了怎么办这是最高频的问题。分几种情况场景处理方法注意事项刚提交未推送git commit --amend直接改无风险已推送但只有自己用这个分支git commit --amend后强制推送确认没有其他人基于这个分支工作已推送多人共用分支不要amend追加一次新提交说明改写公共历史会造成其他人冲突历史中较早的提交git rebase -i用 reword仅限未推送的本地提交我踩过的一个坑有一次在团队共享的分支上amend了已推送的提交然后强制推送结果同事本地拉取时产生了大量冲突花了半天才理顺。从那以后我就定了个规矩公共分支上的提交信息写错了宁可追加一条“修正上次提交信息”的提交也不改写历史。5.2 提交信息太长被截断前面说过标题行控制在50字符以内。如果你发现标题被截断了说明写太长了。解决办法是把细节移到正文里标题只保留最核心的信息。比如“修复了用户在使用手机号登录时因为验证码过期导致无法登录的问题”这个标题太长了。可以改成“fix(auth): 修复验证码过期导致的登录失败”具体细节放正文。5.3 团队新人不按规范提交这是团队落地时最常见的问题。我的经验是三道防线模板提示配置.gitmessage让新人每次提交都能看到格式要求。自动校验配置commitlint钩子不符合规范直接拒绝并给出明确的错误提示。代码审查在review时把提交信息也纳入审查范围信息写得不清楚就要求修改。三道防线里自动校验是最有效的。人都有惰性靠自觉不如靠工具。但工具也不能太严格否则会让人产生抵触情绪。我的建议是先严后松项目初期严格执行等大家养成习惯后可以适当放宽一些非关键规则。5.4 中文提交信息在工具里显示乱码这个问题通常出现在Windows环境下。原因是Git的默认编码和终端编码不一致。解决办法是设置git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8然后在终端里把编码也设为UTF-8。如果用的是某些老旧的Git客户端可能还需要在客户端设置里手动指定编码。5.5 如何关联多个issue一次提交关联多个issue可以在脚注里写多行Closes #123 Closes #456或者用逗号分隔Closes #123, #456但要注意不同平台对关键词的识别规则略有差异。GitHub支持Closes、Fixes、Resolves这几种写法后面跟#编号。GitLab也类似。如果你的项目同时托管在多个平台建议查一下各平台的文档确认。5.6 提交信息里能不能放表情符号技术上可以Git不限制提交信息的内容。但我的建议是谨慎使用。表情符号在不同终端、不同操作系统上的显示效果不一致有些环境可能显示成方块。而且表情符号会增加标题的字符宽度容易导致截断。如果你确实想用建议只在标题的类型前缀位置用比如用特定符号代替feat、fix这些文字。但这样会牺牲可读性不熟悉的人看不懂。我的做法是干脆不用保持纯文本兼容性最好。5.7 常见问题速查表问题现象可能原因解决方法提交被拒绝提示格式错误commitlint校验不通过按提示修改提交信息格式标题显示不全超过50字符精简标题细节移到正文正文显示混乱单行超过72字符手动在合适位置换行关联issue没自动关闭关键词拼写错误或格式不对检查是否用了Closes/Fixes #编号中文显示乱码编码设置不一致设置i18n.commitEncoding为utf-8amend后推送被拒绝远程有新的提交先pull --rebase再推送钩子不生效husky未正确初始化重新执行husky install6. 团队落地与长期维护的经验6.1 规范要写进贡献指南提交信息规范不能只停留在口头必须写进项目的CONTRIBUTING.md里。内容要包括格式要求、类型列表、标题长度限制、正文写法、脚注关键词。最好再配几个正例和反例让人一看就懂。贡献指南里的规范要简洁不要写成一篇论文。新人没耐心读长文把最核心的规则用列表列出来就行。详细的解释可以放在单独的文档里需要的时候再查。6.2 代码审查时把提交信息纳入检查项代码审查不只是看代码提交信息也是审查对象。我在review的时候如果看到提交信息写得不清楚会直接留言要求修改。这不是吹毛求疵而是因为提交信息是代码库的长期资产它的质量直接影响项目的可维护性。审查提交信息主要看几点标题是否清晰、正文是否解释了原因、是否关联了issue、粒度是否合理。如果一次提交里混了多个不相关的改动我会要求拆分。6.3 定期整理提交历史项目运行一段时间后提交历史可能会变得杂乱。如果项目还没发布正式版本可以考虑用rebase整理历史把零散的提交合并成有意义的单元。但如果已经发布过版本就不要动历史了因为已经有人可能基于这些提交做了工作。整理历史的原则是只整理未推送的本地提交已推送的公共历史不动。这是铁律违反它会给团队带来麻烦。6.4 工具链的维护commitlint、husky这些工具会随着版本更新而变化配置方式也可能调整。建议在项目里锁定版本号避免因为工具升级导致钩子失效。同时在CI流程里也加一道提交信息校验作为本地钩子的补充。因为本地钩子可以被绕过git commit --no-verifyCI上的校验才是最后一道防线。CI里校验提交信息的思路是在流水线里加一个步骤检查最近一次提交的信息是否符合规范。如果不符合直接让流水线失败。这样即使有人绕过了本地钩子也过不了CI这一关。6.5 我个人的一些习惯最后分享几个我自己的习惯不一定适合所有人但可以参考提交前先git diff --staged看一眼确认暂存的内容和提交信息描述的一致。标题写完后默读一遍如果读起来别扭说明没写清楚。正文里多写“因为”、“所以”、“但是”这些连接词能帮你把逻辑讲清楚。关联issue用Closes而不是Fixed因为Closes更通用GitHub和GitLab都认。破坏性变更一定要在脚注里用BREAKING CHANGE:标明这关系到版本号自动升级的正确性。这套实践我用了好几年带过几个团队落地效果是实打实的。代码审查时间缩短了问题回溯速度快了发版流程也自动化了。投入的成本就是每次提交多花三十秒回报却是长期的。这笔账怎么算都值。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
