Git提交信息最佳实践：从烂账到清晰历史-北京尧图网络

1. 为什么你的提交历史总像一本烂账你有没有过这种经历三个月前改了一行代码现在线上出了个诡异的 bug你翻遍提交记录想找到当时为什么这么改结果看到的全是“fix bug”“update”“修改一下”“111”这种提交信息。那一刻你恨不得穿越回去把当时的自己揍一顿。更惨的是当你需要回滚某个功能时面对满屏的“update”你根本不知道哪一次提交才是你要找的那个版本。这不是个别现象。我见过太多项目提交历史打开一看前二十条里有八条叫“修复问题”五条叫“优化代码”三条叫“临时提交”剩下四条是“aaa”“test”“123”这种完全放弃治疗的内容。这种提交历史有和没有区别不大因为它提供不了任何有效信息。Git commit message 的最佳实践说白了就是一件事让你未来的自己、你的同事、以及任何需要理解这段代码变更的人能够在不问你本人的情况下快速搞清楚“这次提交到底干了什么、为什么这么干”。它不是什么高深的技术但它是一个团队代码素养最直接的体现。你写提交信息的水平基本等于你留给后来者的路标质量。这篇文章适合所有用 Git 的人——不管你是刚学会git add和git commit的新手还是已经提交过几千次但从来没认真想过提交信息该怎么写的老手。我会从最基础的结构讲起一直讲到团队协作中的约定、工具链的配合、以及那些只有踩过坑才知道的细节。看完之后你至少能做到打开任何一个项目的提交历史一眼就能看出哪些提交值得看哪些可以跳过。先说一个我自己的真实教训。早年间参与一个多人协作的项目有次排查一个线上问题需要找到某个配置项是什么时候被改动的。我用git log -p翻了整整一个下午因为提交信息全是“修改配置”“更新参数”这种根本没法用git log --grep来过滤。最后是靠git blame一行一行追才定位到那次改动。如果当时的提交信息写的是“将超时时间从 30s 调整为 60s 以应对高峰期请求堆积”我可能五分钟就搞定了。这就是提交信息质量带来的效率差距一次可能只差几十分钟但一个项目生命周期里累积起来就是巨大的时间浪费。2. 一条合格的提交信息到底长什么样2.1 七条规则撑起的基本骨架关于提交信息的写法社区里流传最广的是 Chris Beams 总结的“七条规则”我把它翻译成大白话结合自己的理解重新讲一遍第一条标题和正文之间空一行。这不是强迫症而是 Git 本身的约定。Git 会把第一行当作提交标题subject空行之后的内容当作正文body。很多工具——比如git log --oneline、GitHub 的提交列表、各种 Git GUI——都只显示第一行。如果你不空行整个提交信息会被当成标题显示出来就是一坨。第二条标题控制在 50 个字符以内。为什么是 50因为 GitHub 的提交列表在 50 个字符左右会截断git log --oneline在终端里也差不多是这个宽度。超过 50 个字符标题就会被截断成“...”读者看不到完整信息。理想状态是 50 以内硬上限是 72。你可以在终端里用echo -n 你的标题 | wc -c来数。第三条标题首字母大写。这是英文写作的习惯中文提交信息不涉及这个问题。但如果你用英文写提交信息首字母大写是基本礼貌。第四条标题末尾不加句号。标题是标题不是句子。加了句号显得冗余而且浪费一个字符。第五条标题用祈使句。什么叫祈使句就是“做某事”的语气而不是“做了某事”或“正在做某事”。比如“修复登录超时问题”而不是“修复了登录超时问题”或“正在修复登录超时问题”。为什么因为 Git 本身生成的提交信息就是祈使句比如Merge branch feature、Revert xxx。你的提交信息应该和 Git 自动生成的保持一致。一个简单的检验方法你的标题能不能填进“这次提交将___”这个句子里能就是祈使句。第六条正文每行控制在 72 个字符以内。因为git log在终端里显示时默认会缩进 4 个空格72 4 76大多数终端的默认宽度是 80 个字符。超过 72终端就会自动换行看起来很难受。第七条正文用来说明“是什么”和“为什么”而不是“怎么做”。代码本身已经说明了“怎么做”你不需要在提交信息里重复代码的逻辑。你需要解释的是这次变更解决了什么问题为什么选择这种方案而不是另一种有什么副作用或注意事项这七条规则看起来多但核心就一句话让提交信息在最小空间内传递最大信息量。2.2 标题的写法动词开头说清楚干了什么标题是提交信息里最重要的部分因为大多数人只看标题。一个好的标题应该让读者在 3 秒内判断出这次提交是否与他要找的内容相关。我推荐的结构是动词对象补充说明可选。举几个例子对比差的标题好的标题差在哪里修复 bug修复用户头像上传时的格式校验错误太笼统不知道修了什么更新代码将请求超时时间从 30s 调整为 60s不知道更新了什么优化减少首页列表渲染的重复计算不知道优化了什么修改配置关闭生产环境的调试日志输出不知道改了什么配置提交添加订单导出功能的单元测试等于没写常用的动词有添加、修复、更新、删除、重构、优化、调整、移除、重命名、提取、合并、回滚。这些动词本身就携带了变更类型的信息读者一看就知道这次提交的性质。如果你的项目使用 Scrum 或类似的管理方式可以在标题前面加上任务编号比如[PROJ-123] 修复用户头像上传时的格式校验错误。这样方便追溯但注意任务编号会占用标题的字符数所以后面的描述要更精炼。2.3 正文的写法解释“为什么”而不是“做了什么”正文是很多人忽略的部分。他们觉得标题写清楚就行了正文随便写写或者干脆不写。但正文恰恰是提交信息价值最高的地方因为标题只能容纳 50 个字符很多背景信息塞不进去。正文应该回答三个问题为什么要做这次变更是修了一个 bug还是为了满足某个新需求还是为了优化性能为什么选择这种方案有没有考虑过其他方案为什么最终选了这个这次变更有什么影响有没有破坏性变更有没有需要特别注意的地方我举个例子。假设你要把某个接口的超时时间从 30 秒改成 60 秒标题可以写“将支付接口超时时间从 30s 调整为 60s”正文可以这样写近期支付高峰期频繁出现超时告警经排查发现部分银行的回调处理时间在 40-50 秒之间原有的 30 秒超时设置会导致这些请求被提前中断进而触发重试逻辑造成重复扣款的风险。将超时时间调整为 60 秒后可以覆盖绝大多数银行的回调处理时间。同时增加了超时后的日志记录便于后续观察是否还有需要进一步调整的空间。注意这次变更只调整了支付接口的超时时间其他接口的超时配置保持不变。这样的正文任何人看了都能理解这次变更的背景、方案和影响。三个月后再来看也能快速回忆起当时的情况。2.4 那些年我们踩过的提交信息坑说几个我亲身经历或见到的典型问题坑一用git commit -m fix提交所有东西。有些人习惯把所有改动攒在一起然后一个fix提交完事。这种提交信息等于没写而且把多个不相关的变更混在一起回滚的时候极其痛苦。正确的做法是一个提交只做一件事提交信息描述这件事。坑二提交信息里写“WIP”然后忘了改。工作未完成时提交一个 WIPWork In Progress标记是可以的但合并到主分支之前一定要整理提交历史把 WIP 提交合并或改写。否则主分支的历史里全是 WIP看起来很不专业。坑三用中文标点符号。这个坑很隐蔽。中文的逗号、句号、冒号在终端里显示时占两个字符宽度而且有些工具处理中文标点会出问题。建议提交信息统一用英文标点即使内容是中文。坑四标题太长被截断。我见过有人把整个变更描述都塞进标题结果在 GitHub 上显示出来是“修复用户登录时偶尔出现的超时问题以及相关的日志记录和错误处理逻辑...”后面的内容全被截断了。标题就是标题详细内容放正文。坑五提交信息与代码变更不符。这个最要命。有人改了 A 文件提交信息写的是修改 B 功能。这种不一致会让后来者完全迷失方向。每次提交前用git diff --cached确认一下暂存区的内容确保提交信息描述的就是这些变更。3. 团队协作中的提交信息约定3.1 约定式提交让机器也能读懂提交信息个人项目里提交信息写得随意一点问题不大。但团队协作中提交信息需要有一定的规范性否则每个人的风格不同历史记录就会很混乱。目前最流行的团队约定是Conventional Commits约定式提交。它的基本格式是类型[可选的作用域]: 描述 [可选的正文] [可选的脚注]类型包括feat新功能fix修复 bugdocs文档变更style代码格式调整不影响功能refactor重构既不是新功能也不是修 bugperf性能优化test测试相关build构建系统或外部依赖变更ci持续集成配置变更chore其他不修改源代码或测试的变更举个例子feat(订单模块): 添加批量导出订单的功能支持按时间范围筛选后批量导出为 CSV 文件单次最多导出 10000 条记录。导出操作会记录在操作日志中。 Closes #1234这种格式的好处是机器可以解析。比如可以自动生成变更日志changelog可以根据类型自动决定版本号是 major、minor 还是 patch。很多工具链——比如 semantic-release、standard-version——都依赖这种格式。但我要说一句实话约定式提交不是银弹。它增加了写提交信息的成本如果团队没有配套的工具链来利用这些结构化信息那这些额外的格式要求就只是负担。我见过一些团队强行推行约定式提交但既没有自动生成 changelog也没有做版本自动化结果大家只是多打了几个前缀字符实际收益很小。所以我的建议是如果你的团队有自动化发布、自动生成 changelog 的需求那就用约定式提交如果没有用简洁清晰的自由格式就够了不必为了规范而规范。3.2 提交粒度一个提交只做一件事提交粒度是比提交信息格式更根本的问题。一个提交如果混了多个不相关的变更提交信息再怎么写都写不好。因为你要么只能概括其中一个变更要么写一个笼统的标题把多个变更都塞进去。什么叫“一个提交只做一件事”举个例子你正在开发一个新功能过程中发现了一个不相关的 bug顺手修了。这时候你应该做两个提交一个提交修 bug一个提交加功能。而不是一个提交里既有 bug 修复又有新功能。为什么因为如果后来发现那个 bug 修复有问题需要回滚你可以单独回滚那一个提交而不影响新功能。如果混在一起回滚就会把新功能也一起回滚掉。实际操作中你可以用git add -p来交互式地选择要暂存的代码块把不相关的变更分开提交。这个命令我强烈推荐每个 Git 用户都学会它让你可以精确控制每个提交的内容。3.3 代码审查中的提交信息在代码审查Code Review中提交信息是审查者的第一手资料。审查者打开一个合并请求Merge Request / Pull Request首先看到的就是提交列表。如果提交信息清晰审查者可以快速了解每个提交的意图有针对性地看代码。如果提交信息全是“update”审查者就只能一行一行看代码来理解变更效率极低。我自己的习惯是在提交合并请求之前先自己用git log --oneline看一下提交列表问自己一个问题——如果我是审查者只看这些提交信息能不能理解这个合并请求做了什么如果不能就整理一下提交历史该合并的合并该改写的改写。改写提交历史用git rebase -i它可以把多个提交合并成一个也可以修改提交信息。但注意只对还没有推送到远程仓库的提交做 rebase。已经推送的提交如果被 rebase会导致其他人的本地历史和远程历史不一致造成麻烦。4. 工具链如何帮你写出更好的提交信息4.1 commitlint自动检查提交信息格式如果你在团队中推行了约定式提交可以用 commitlint 来自动检查提交信息是否符合格式。它的工作原理是在 Git 的 commit-msg 钩子里运行如果提交信息不符合配置的规则就拒绝这次提交。安装和配置很简单npm install --save-dev commitlint/cli commitlint/config-conventional然后在项目根目录创建commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional] };再配置 Git 钩子。最简单的方式是用 huskynpx husky install npx husky add .husky/commit-msg npx --no -- commitlint --edit $1这样每次提交时commitlint 会自动检查提交信息。如果格式不对提交会被拒绝并提示具体哪里不符合规则。但我要提醒一点commitlint 的规则不要太严格。我见过一些团队把规则配得非常细比如要求作用域必须是预定义的几个值之一结果开发人员经常因为作用域写错而被拒绝提交反而降低了效率。规则应该服务于目标而不是为了规则而规则。4.2 commitizen交互式生成提交信息commitizen 是一个交互式工具它会在你提交时逐步询问变更类型、作用域、描述等信息然后自动生成符合约定式提交格式的提交信息。安装npm install --save-dev commitizen cz-conventional-changelog配置 package.json{ scripts: { commit: cz }, config: { commitizen: { path: cz-conventional-changelog } } }之后用npm run commit代替git commit就会进入交互式界面。这个工具对新手很友好因为它不需要你记住格式跟着提示走就行。但对老手来说可能有点繁琐因为每次提交都要回答好几个问题。我个人的做法是新手阶段用 commitizen 养成习惯熟练之后直接手写效率更高。4.3 gitmoji用表情符号标记提交类型gitmoji 是一个用表情符号来标记提交类型的约定。比如用 ✨ 表示新功能表示修 bug 表示文档变更。说实话我对 gitmoji 的态度比较矛盾。一方面它确实让提交历史看起来更生动一眼就能区分不同类型的提交。另一方面表情符号在不同终端、不同工具里的显示效果不一致有些地方显示为方框或乱码反而影响可读性。而且表情符号的语义不如文字明确不是所有人都能记住每个表情代表什么。我的建议是如果团队所有人都喜欢并且习惯用 gitmoji那就用如果有任何一个人觉得不方便那就不要用。提交信息的首要目标是清晰传达信息而不是好看。4.4 一个好用的 Git 别名让查看提交历史更高效最后分享几个我常用的 Git 别名它们让查看提交历史变得非常方便。把这些加到你的~/.gitconfig里[alias] lg log --color --graph --prettyformat:%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)%an%Creset --abbrev-commit last log -1 HEAD --stat unstage reset HEAD -- amend commit --amend --no-editgit lg是我用得最多的别名它用图形化的方式显示提交历史包含提交哈希、分支引用、提交标题、相对时间和作者。比默认的git log好看得多也实用得多。git last查看最后一次提交的详细信息包括改了哪些文件。git unstage把文件从暂存区移出。git amend把当前改动追加到上一次提交不修改提交信息。这些别名看起来是小事但每天用几十次累积起来节省的时间很可观。5. 从提交历史反推项目质量5.1 提交历史是项目的一面镜子我有个习惯拿到一个新项目先看它的提交历史。如果提交历史清晰、规范、有逻辑那这个项目的代码质量通常不会太差。如果提交历史乱七八糟那代码质量大概率也有问题。这不是玄学。提交历史反映的是开发者的工作习惯和态度。一个连提交信息都懒得好好写的人很难想象他会认真写注释、写测试、考虑边界情况。反过来一个提交信息写得一丝不苟的人通常对代码质量也有较高的要求。具体看什么我看三点第一提交频率和粒度。如果一个人每天只提交一两次每次提交一大堆文件说明他的工作方式是“攒着一起提交”。这种方式的问题是提交历史没有反映真实的开发过程回滚和排查都很困难。健康的提交频率应该是每完成一个小功能或修复一个小问题就提交一次一天可能提交几次到十几次。第二提交信息的质量。前面已经说了很多这里不重复。重点看标题是否清晰、正文是否解释了“为什么”。第三提交之间的逻辑关系。好的提交历史应该像一篇有逻辑的文章每个提交都是文章的一个段落前后有承接关系。如果提交之间跳跃性很大说明开发过程比较混乱。5.2 用提交历史做代码审查代码审查不一定非要在合并请求里做。有时候直接看提交历史也能发现很多问题。比如你可以用git log --since1 week ago --oneline看最近一周的提交。如果发现某个人的提交信息全是“fix”而且每次提交都改了很多文件那可能说明他的工作方式需要调整。再比如你可以用git log --grepfix --oneline搜索所有包含“fix”的提交。如果数量特别多可能说明代码质量有问题bug 频繁出现。还可以用git shortlog -sn看每个人的提交数量。这不是为了比较谁贡献大而是为了了解团队的工作分布。如果某个人提交数量特别多可能说明他承担了过多的工作如果某个人提交数量特别少可能说明他遇到了困难或者参与度不够。5.3 提交信息与变更日志的自动化生成如果你的项目使用约定式提交可以用工具自动从提交历史生成变更日志。常用的工具有 standard-version 和 semantic-release。standard-version 的用法很简单npm install --save-dev standard-version npx standard-version它会根据提交历史中的feat、fix等类型自动决定版本号是 major、minor 还是 patch然后生成 CHANGELOG.md 文件并打上 Git 标签。semantic-release 更激进它可以在 CI 流程中全自动完成版本发布分析提交历史、决定版本号、生成变更日志、发布到 npm、创建 Git 标签和 GitHub Release。适合成熟的持续交付项目。但这两个工具都有前提条件提交信息必须严格遵循约定式提交格式。如果提交信息不规范生成的变更日志就会有问题。所以工具链是辅助核心还是人。6. 那些只有踩过坑才知道的细节6.1 提交信息里的时态和语态英文提交信息里时态和语态是个容易搞混的地方。前面说了用祈使句但具体怎么操作对比一下祈使句Fix login timeout issue推荐过去时Fixed login timeout issue不推荐现在进行时Fixing login timeout issue不推荐第三人称Fixes login timeout issue不推荐为什么推荐祈使句因为 Git 自己生成的提交信息就是祈使句。你执行git merge时Git 生成的提交信息是Merge branch xxx而不是Merged branch xxx。你的提交信息应该和 Git 保持一致。中文提交信息不涉及时态问题但要注意语态。用主动语态不用被动语态。比如“修复登录超时问题”而不是“登录超时问题被修复”。6.2 提交信息里的标点符号中文提交信息里标点符号的使用有几个注意点标题末尾不加句号。这个前面说过了中英文都一样。标题内部用空格代替逗号。比如“修复登录超时问题增加重试逻辑”比“修复登录超时问题增加重试逻辑”更清爽。因为逗号在终端里显示时容易和文字混在一起空格更清晰。正文里正常使用标点。正文是完整的句子该用逗号用逗号该用句号用句号。但建议用英文标点因为中文标点在有些终端里显示宽度不一致影响排版。避免使用特殊符号。比如、#、$这些符号在 Git 里有特殊含义#是注释在某些工具里有特殊用途提交信息里尽量少用。6.3 提交信息与分支策略的配合提交信息的风格应该和分支策略配合。比如如果你用Git Flow主分支上的提交信息应该更正式、更完整因为主分支的历史是项目的正式记录。功能分支上的提交信息可以随意一些因为合并时会被压缩或改写。如果你用Trunk-Based Development所有提交都直接进主分支那每条提交信息都要认真写因为主分支的历史就是项目的全部历史。如果你用GitHub Flow功能分支合并到主分支时通常用 Squash Merge把多个提交压缩成一个。这时候功能分支上的提交信息可以随意但 Squash 后的那一条提交信息必须写好。我个人的偏好是不管用什么分支策略每条提交信息都认真写。因为你永远不知道什么时候需要回滚到某一个具体的提交而清晰的提交信息是回滚时最重要的参考。6.4 修改提交信息的正确姿势提交信息写错了怎么办分两种情况如果提交还没有推送到远程仓库直接用git commit --amend修改。这个命令会打开编辑器让你修改最后一次提交的信息。如果只想改信息不改内容加--no-edit之外的参数git commit --amend -m 新的提交信息如果提交已经推送到远程仓库情况就复杂了。如果你确定没有其他人基于这个提交做开发可以用git commit --amend修改后强制推送git commit --amend -m 新的提交信息 git push --force-with-lease注意用--force-with-lease而不是--force。--force-with-lease会在推送前检查远程分支是否有你本地没有的提交如果有就拒绝推送避免覆盖别人的工作。如果已经有其他人基于这个提交做了开发那就不要改写了。改写已经推送的提交历史会给其他人造成麻烦。正确的做法是接受这个不完美的提交信息在后续的提交中补充说明。6.5 提交信息里的引用和关联提交信息里可以引用其他提交、问题单、合并请求等。常用的格式Closes #123关闭编号为 123 的问题单Fixes #456修复编号为 456 的问题单See also #789关联编号为 789 的问题单Revert xxx回滚某次提交这些引用不仅方便追溯还能触发一些自动化操作。比如 GitHub 会在合并请求合并时自动关闭被Closes引用的 issue。但注意不要滥用。我见过有人在提交信息里塞了十几个Closes结果合并时一次性关闭了一堆不相关的问题单。引用要精确只引用真正相关的内容。7. 从今天开始让你的提交历史变得有用说了这么多最后落到实操上。如果你之前没有认真写过提交信息我建议你从今天开始做三件事第一每次提交前问自己一个问题如果三个月后的我看到这条提交信息能不能在不看代码的情况下理解这次变更如果不能就重新写。第二从下一个项目开始坚持“一个提交只做一件事”。用git add -p来精确控制暂存内容把不相关的变更分开提交。这个习惯一旦养成你会发现回滚和排查变得轻松很多。第三在团队里推动一个简单的提交信息规范。不需要太复杂哪怕只是要求“标题说清楚干了什么正文解释为什么”这一条就能让提交历史的质量提升一个档次。我自己的体会是写提交信息这件事投入产出比极高。每条提交信息多花 30 秒但可能在未来的某一天帮你节省 30 分钟甚至 3 小时。而且这个收益是复利的——项目运行越久提交历史越长清晰的提交信息带来的价值就越大。最后分享一个小技巧如果你不知道怎么写正文可以试着用“因为...所以...”的句式来组织。比如“因为支付高峰期回调处理时间较长所以将超时时间从 30s 调整为 60s”。这个句式强迫你解释原因而原因恰恰是提交信息里最有价值的部分。

Git提交信息最佳实践：从烂账到清晰历史

相关推荐

Kettle 异构数据同步实战：Oracle 到 MySQL 跨库复制方案与避坑指南

Claude Code + MasterGo：Android 布局全自动生成实践

PatchPae2原理详解：如何破解Win8.1 32位4G内存限制

更多资讯

非合作博弈下的居民负荷分层调度与双层鲸鱼算法求解

数控加工仿真软件3.7实战指南：刀路验证与避坑技巧

上位机与汇川PLC的Modbus TCP通讯：视觉结果回写与联调避坑指南

大年初七晨听歌：一小时的选曲逻辑与实操记录

多厂商网络设备登录配置全解析：Console、Telnet、SSH与Web实战

别再背Docker命令了：从镜像到Compose的实战心法

今日更新

智能硬件视频会议集成：从芯片选型到场景落地的全栈实践

FFmpeg音视频处理与5路RTMP推流实战：从原理到118克盒子部署

RK3528+1GB内存如何变身直播节点？硬编解码与六协议实战复盘

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？