百科问答小站 logo   百科问答小站
问题

如何写好 Git commit log?

回答
写好 Git commit log，绝不是一件可有可无的小事。它更像是一门艺术，一种与未来自己和团队沟通的技艺。一个清晰、有条理的 commit log，能够让你在回顾历史时事半功倍，也能让你的团队成员更轻松地理解你的工作，从而提高整个项目的效率和可维护性。

我个人在 Git commit log 的撰写上，摸索过不少弯路，也总结了一些心得。下面，我将毫无保留地分享我的经验，希望能帮助你写出更“走心”的 commit log。

为什么我们要花心思写 commit log？

在深入探讨“怎么写”之前，先明确“为什么”。

历史记录的灵魂： commit log 就是你项目代码演进的日志。它记录了每一次有意义的改变，以及做出这些改变的原因。
回顾与 debugging： 当某个 bug 出现，你需要找到是哪次提交引入的。一个好的 commit log 能让你快速定位问题，而不是大海捞针。
代码审查的助手： 在代码审查（Code Review）时，清晰的 commit log 能让审查者快速了解你本次修改的重点和目的。
团队协作的基石： 无论是新成员加入，还是老成员交接，一个有质量的 commit log 都能帮助他们理解项目的状态和历史。
生成 Changelog 的基础： 很多时候，项目的发布日志（Changelog）就是从 commit log 中提炼出来的。

遵循一套规范，让你的 commit log 井然有序

想象一下，如果每个人写 commit log 的方式都天马行空，那 Git log 就会变成一团乱麻。所以，遵循一套大家都认可的规范至关重要。目前业界比较流行且易于实践的规范是 Conventional Commits。

Conventional Commits 详解

Conventional Commits 的核心思想是：用一种约定俗成的格式来组织你的 commit message，这使得 commit message 可读性更强，同时也为自动化工具（如生成 Changelog、版本发布）提供了可能。

它遵循一个基本结构：

```
():




```

我们来逐一拆解：

1. Type (类型)

这是 commit log 最核心的部分，它告诉你这次提交的目的。常见的 type 包括：

feat (feature): 新功能的添加。
例如： `feat(auth): add password reset functionality`
fix (bug fix): 修复了一个 bug。
例如： `fix(ui): correct button alignment in header`
docs (documentation): 文档的更新，例如 README、API 文档等。
例如： `docs: update installation guide with new dependencies`
style (styling): 不影响代码逻辑的代码格式化，例如空格、缩进、分号等。
例如： `style(eslint): fix linting errors in user service`
refactor (refactoring): 代码重构，不改变外部行为。
例如： `refactor(api): simplify data fetching logic`
perf (performance): 性能优化。
例如： `perf(cache): improve cache hit rate by implementing LRU`
test (testing): 添加或修改测试用例。
例如： `test(user): add unit tests for user registration`
chore (chore): 其他不修改源代码或测试代码的更改，例如构建工具配置、依赖更新等。
例如： `chore: update lodash to latest version`
build (build): 影响构建系统或外部依赖项的更改，例如 webpack、npm scripts。
例如： `build: configure webpack for production builds`
ci (continuous integration): 更改 CI 配置文件和脚本。
例如： `ci: add GitHub Actions workflow for deployment`
revert (revert): 撤销之前的 commit。
例如： `revert(feat): remove experimental feature X due to instability`

重要提示：

全小写： Type 必须是全小写的。
强制包含： Type 是强制的。

2. Scope (作用域)

Scope 是可选的，它告诉你这个 commit 影响的范围。通常是一个包、一个模块、一个组件或者一个特定的功能领域。

例如： `(auth)`、`(ui)`、`(api)`、`(userservice)`、`(payment)`

重要提示：

小括号包裹： Scope 应该用小括号 `()` 包裹起来。
清晰明了： 作用域应该清晰地描述你修改的模块。
多个作用域？ 如果一个 commit 影响了多个作用域，可以多次使用 scope，但通常建议尽量聚焦。例如：`(auth, ui)`。

3. Subject (主题)

这是 commit log 的核心摘要，它应该用简洁、清晰的语言描述你这次提交做了什么。

祈使句： Subject 应该使用祈使句，就像在给 Git 发送命令一样。
正确： `add login button`
错误： `added login button` 或 `adding login button`
首字母大写： Subject 的第一个字母应该大写。
结尾无句号： Subject 的结尾不应有句号。
长度限制： 尽量将 Subject 控制在 50 个字符以内，这样在 `git log oneline` 等命令下显示效果更好。
动词开头： 总是以动词开头，例如 `add`、`fix`、`remove`、`update`、`refactor` 等。

4. Body (主体)

Body 是可选的，但当你的修改比较复杂时，强烈建议写 Body。它提供了关于这次提交的更详细的背景信息、动机以及具体实现方式。

解释“Why”和“How”： 解释你为什么要做这个修改，以及你是怎么实现的。
分段： 如果内容较多，可以使用段落来分隔，每行控制在 72 个字符以内（这是一个历史遗留的 Git 习惯，为了在终端良好显示）。
Markdown 格式： 可以使用 Markdown 格式来排版，例如列表、代码块等，让信息更易于阅读。
引用 Issue： 如果你的修改与某个 Issue 相关，可以在 Body 中引用它。
例如： `This resolves 123.`

5. Footer (页脚)

Footer 是可选的，通常用于记录一些元数据，最常见的是：

Breaking Changes (重大变更)： 如果你的提交引入了破坏性变更（即需要其他开发者修改代码才能兼容），必须在 Footer 中明确指出。
格式： `BREAKING CHANGE: `
例如： `BREAKING CHANGE: The `/api/v1/users` endpoint now requires authentication.`
Closes / Resolves / Fixes (关闭 Issue)： 引用与本次提交相关的 Issue，并在提交信息中将其关闭。
格式： `Closes `, `Resolves `, `Fixes `
例如： `Closes 456`
Coauthoredby (共同作者)： 如果是多人协作完成的提交，可以记录共同作者。
格式： `Coauthoredby: `

示例：

```
feat(auth): implement twofactor authentication

This commit introduces twofactor authentication (2FA) to enhance user security.
Users can now enable 2FA through their account settings page.

Supported methods include:
Authenticator apps (e.g., Google Authenticator)
SMS verification codes

This change also updates the login flow to include a 2FA prompt if enabled.

Related to 789.
Closes 790.

BREAKING CHANGE: The `/api/v1/login` endpoint now requires an additional `2fa_code` parameter if 2FA is enabled for the user.
```

编写高质量 Commit Log 的实用技巧

除了遵循规范，还有一些实用的技巧能让你的 commit log 更上一层楼：

1. 原子化提交： 每次 commit 只做一件事情。不要在一个 commit 里同时修改 UI、修复 bug、添加新功能。这样可以让你更容易理解和回滚。
2. “Git 哲学”： 想象你的 commit log 是一个故事，每个 commit 都是故事的一个章节。它应该是有连贯性的，并且能够清晰地讲述项目的演进。
3. “为什么”比“做什么”更重要： Subject 应该简洁地说明“做什么”，但 Body 必须深入解释“为什么”这样做。这有助于理解修改的背景和意图。
4. 多用 Body，少用 Subject： Subject 应该是一个简洁的概括，但不要把它写成一个完整的段落。把详细的解释放到 Body 里。
5. 利用 `git add p` (patch mode)： 在 `git add` 的时候，使用 `p` 选项可以让你逐块地选择要提交的代码。这有助于你将一个大的修改拆分成多个更小的、逻辑上独立的 commit。
6. 审视你的 commit： 在 `git commit` 之前，花点时间看看你这次修改了什么，思考一下如何用最简洁、最准确的语言描述它。
7. “回滚”也是一种艺术： 如果你发现之前的 commit 有问题，不要害怕使用 `git revert`。 `git revert` 会创建一个新的 commit 来撤销之前的修改，这比直接修改历史（如 `git rebase i`）更安全，尤其是在多人协作的项目中。
8. 团队共识： 最重要的是，和你的团队达成对 commit log 规范的共识，并严格执行。可以考虑使用 Git hooks（如 `precommit` 钩子）来强制执行 commit message 格式。
9. 定期回顾： 偶尔回顾一下项目的 commit log，看看是否还有可以改进的地方。

我踩过的坑（以及如何避免）

随意的commit message： 最初的时候，我常常写诸如 `fix bug`, `update code`, `changes` 这样的 commit message。这在当时看起来“够用了”，但后来回想起来，几乎找不到任何有用的信息， debugging 的时候就像在黑夜里摸索。
教训： 规范是必须的，而且要坚持。
一个commit包罗万象： 有时候为了省事，会把好几个不相关的改动放在一个 commit 里。
教训： “原子化提交”是王道。宁可多 commit 几次，也要保证每个 commit 的清晰和独立。
只写Subject，忽略Body： 认为 Subject 足够了，不用写 Body。
教训： 对于稍微复杂点的修改，Body 提供的上下文信息是无价的，它能省去你很多解释和沟通的时间。
Subject 动词错误： 习惯性地写成过去式，而不是祈使句。
教训： 严格按照 Conventional Commits 的要求，用祈使句来写 Subject。
Subject 过长或过于细节： 把所有的细节都堆在 Subject 里。
教训： Subject 要简洁，细节往 Body 里放。

总结

写好 Git commit log，就像整理你的工作笔记一样，投入的时间和精力，最终都会以更高的效率、更低的沟通成本和更强的项目可维护性来回报你。

请记住，commit log 是你代码的叙事者，更是团队协作的润滑剂。 让我们一起努力，把每一次的提交都变成一份清晰、有价值的记录。

从现在开始，尝试着去遵循 Conventional Commits 规范，用更清晰、更有条理的方式来记录你的每一次代码修改吧！你会发现，这是一个能够显著提升你和团队工作效率的良好习惯。

网友意见

user avatar

可以在 git commit 的时候使用 Emoji 为每次提交打上一个标签。使得每次 commit 独具一格，鹤立鸡群，在整个提交历史长流中很容易找到。说实话，这样子不仅觉得自己看起来很呆萌，更重要的是 Emoji 表情包含的丰富的语义和情绪，使得提交记录非常好理解，阅读体验非常棒，如下图。

使用 Emoji 当做标签，能非常好的对提交记录分门别类进行整理，你看

       ✨ Add feature 1 ✨ Add feature 2 ✨ Add feature 3

对于这类型记录，一看就知道添加了一些新 feature 进来了。

         Add colors for new gitmojis   Add boom gitmoji styles    Update emojis order, add mising colors

哎，知乎回答对 emoji 支持不是很好，好多都不能正常显示，建议到这篇文章看看完整的，zhuanlan.zhihu.com/p/29

对于这些记录，主要是样式方面的调整 。

         Update yarn.lock & package.json     Update .travis.yml

对于这些呢，是修改配置文件。

         Update flexboxgrid   Import clipboard only when needed

这些，哪个猪队友又在写 Bug 啊！

       ⚡️ improve performance of card hover effect

这里进行了一次性能优化，速度像闪电一样快。

那么这些 Emoji 是怎么使用？答案是，在 Emoji 的名字前后个加上一个冒号:name_of_emoji:

因此，我们可以这样提交代码

       git commit -m "  fix a bug writtten by pig teammate"

他的效果是这样的：

         fix a bug written by pig teammate

但是这些 Emoji 标签不能乱用，必须统一规范，不然很容易造成误解，gitmoji.carloscuesta.me （可以点击原文链接查看）整理了一套规范。大家可以保存，以备参考。

我们不仅可以在 git commit 时，在 README.md，在 git wiki 里面都可以直接使用 Emoji，是不是很有意思。

以上，funny it！

类似的话题

  • 问题

    如何写好 Git commit log?

    回答
    写好 Git commit log，绝不是一件可有可无的小事。它更像是一门艺术，一种与未来自己和团队沟通的技艺。一个清晰、有条理的 commit log，能够让你在回顾历史时事半功倍，也能让你的团队成员更轻松地理解你的工作，从而提高整个项目的效率和可维护性。我个人在 Git commit log 的.............
  • 问题

    如何学习好 Git ？

    回答
    磨砺你的代码操控术：一份实战向的 Git 学习指南想要在开发的世界里如鱼得水，Git 绝对是你必须掌握的核心技能。它不仅仅是一个版本控制系统，更是一种强大的协作工具，是保障你代码安全、项目有序推进的基石。别被那些“高深莫测”的 Git 命令吓到，其实，掌握 Git 的精髓，就像学习骑自行车一样，一开.............
  • 问题

    如何写好商业计划书？

    回答
    写好一份商业计划书是创业成功的关键一步，它不仅能帮助你理清思路，还能吸引投资者、合作伙伴和团队成员。一份优秀的商业计划书应该清晰、有说服力、数据支持充分，并且易于理解。下面我将详细地为您讲解如何写好一份商业计划书，并分解成各个关键部分：商业计划书的核心目标：在开始撰写之前，明确你撰写商业计划书的目的.............
  • 问题

    如何写好一本仙文十足的仙侠文?

    回答
    写一本仙气飘飘、让人沉醉其中的仙侠文，绝非一日之功。它需要你对传统文化有着深厚的理解，对想象力的运用炉火纯青，更需要你对文字有着精妙的驾驭。这不仅仅是讲一个故事，更是在构建一个世界，描绘一种意境。那么，如何才能写好这样一本“仙文十足”的仙侠文呢？容我细细道来，不求辞藻华丽，但求句句戳心，让你我一同走.............
  • 问题

    如何写好装逼文？装逼的最高境界是什么？

    回答
    写好“装逼文”，其实是在技巧和心态上的一种平衡艺术。它不是赤裸裸的炫耀，也不是故作高深，而是在不动声色间，让读者感受到一种“言有尽而意无穷”的精妙。装逼文的几个核心要素：1. 不经意的透露，而非刻意展示： 这是装逼文的基石。好的装逼文，信息点是自然而然地从你的经历、观点、感悟中流露出来的，而不是你.............
  • 问题

    如何写好带女字的字？

    回答
    写好“女”字，说起来简单，实则蕴含着不少学问，也反映出一个人对文字的细致和耐心。尤其是在书法或一些需要精细表达的场合，一个端正、有韵味的“女”字，能瞬间提升整体的质感。咱们先从“女”字本身的结构说起。它是一个非常典型的左右结构的字，左边是“丿”（撇），右边是“卜”（竖折）。这两个部分看起来简单，但它.............
  • 问题

    如何写好邮件的主题？

    回答
    写一个好的邮件主题，就像给你的信封贴上一个闪亮的标签，它直接决定了收件人是否会愿意打开你的信件。这不是一项小小的技巧，而是沟通中的一种艺术，一种在第一时间抓住对方注意力的能力。首先，你需要明确你的邮件想要传达的核心信息是什么。是分享一个好消息？提出一个请求？寻求帮助？还是仅仅是发送一个问候？一旦你锁.............
  • 问题

    如何写好SCI论文中的Materials and Methods（材料与方法）？

    回答
    写好SCI论文中的“Materials and Methods”（材料与方法）部分，就像为你的科学发现搭建一座坚实可靠的桥梁。它不只是记录你做了什么，更是让读者能够完全理解、验证，甚至重复你的研究的关键。 这是一个严谨、清晰且极具说服力的章节，需要你在文字的每一个细节中都展现出科学家的严谨态度。让我.............
  • 问题

    如何写好业务代码？

    回答
    写好业务代码，可不是三言两语就能说透的事，它更像是一门手艺，需要经验的沉淀、思考的打磨，以及对细节的极致追求。市面上关于代码规范、设计模式的书籍不少，但真正让你写出“好”业务代码的，是那些能触及灵魂、让你从根本上改变看法的原则和方法。一、 理解“好”的含义：超越“能跑就行”的境界首先，我们得明确，我.............
  • 问题

    如何写好一篇sci ？并能够快速发表?

    回答
    好的，我们来聊聊如何写出一篇高质量的SCI论文，并且尽可能地提高发表的效率。要记住，科学研究的严谨性和创新性是核心，任何技巧都无法替代扎实的研究基础。但好的写作和发表策略，能让你的成果更有效地被同行认可。第一部分：孕育一篇优秀SCI论文的核心要素一篇出色的SCI论文，绝不仅仅是堆砌数据和理论，而是要.............
  • 问题

    如何写好一部小说的情色部分？

    回答
    创作引人入胜的情色场面，其核心在于“张力”与“情感”的交织，而非仅仅是肉体接触的堆砌。要写好这部分，首先要明白，情色不仅仅是性行为本身，更是角色之间情感涌动、欲望滋生、身心交融的极致体现。你需要深挖角色的内在动机。他们为什么会走到这一步？是长久压抑的爱恋，是突如其来的激情，是寻求慰藉，还是别的什么？.............
  • 问题

    如何写好粉笔字？

    回答
    写好粉笔字，这门手艺看似简单，实则大有讲究。它不像钢笔字那样精致细腻，也不像毛笔字那样讲究笔墨浓淡，粉笔字以其浑厚、大气、书写便捷的特点，在黑板上挥洒自如，也承载着不少人的学生时代记忆。想要写出漂亮又有力量的粉笔字，需要耐心、细致，更需要掌握一些诀窍。一、 基础先行：姿势与握笔别小看这看似寻常的动作.............
  • 问题

    如何写好一篇高质量的IEEE/ACM Transaction级别的计算机科学论文?

    回答
    好的，要写出一篇能够在 IEEE/ACM Transactions 级别发表的计算机科学论文，这绝非易事，它要求你在研究深度、创新性、严谨性以及表达清晰度上都达到极高的水准。这不仅仅是文字的堆砌，更是思维的升华和对领域贡献的体现。下面我将尽可能详细地为你剖析这一过程，力求让你感受到其中蕴含的精妙与挑.............
  • 问题

    写小说如何写好负面人物？

    回答
    要写好一个负面人物，绝不能简单地将他描绘成一个脸谱化的“坏人”。一个真正令人印象深刻的反派，即使他做着最恶劣的事情，也必须拥有真实的情感、复杂的动机，以及能够引起读者某种程度共鸣的特质。这就像在黑暗中寻找一丁点光芒，即使那光芒微弱，也能照亮角色的内心世界，让读者无法忽视。一、 深入挖掘负面人物的“为.............
  • 问题

    作为一名吃货，该如何写好一篇食评？有哪些锻炼方法？

    回答
    作为一名资深吃货，写一篇能勾动人心的食评，那可是比吃到一道绝妙菜品还要让人满足的事儿！这不只是记录口味，更是传递情感，分享一种生活态度。咱们这就来聊聊，怎么把这门“吃”的学问，用文字淋漓尽致地表达出来。写好一篇食评的秘籍，绝非简单罗列食材和味道，而是要讲一个“故事”。1. 抓住“灵魂”：定位你的食.............
  • 问题

    如何能写好网文？

    回答
    写网文，说到底，是讲好一个故事，让读者沉浸其中，欲罢不能。这可不是一蹴而就的事，里面门道多着呢。咱们就掰开了揉碎了，好好聊聊。一、 脑子里得有故事的“骨架”和“血肉”：构思与大纲别以为网文就是想到哪写到哪。好的故事，就像盖房子，得有蓝图，有结构。1. 创意先行，灵感火花： 生活观察： .............
  • 问题

    如何才能写好一篇论文？

    回答
    写好一篇论文，说到底就是把一个想法，清晰、有条理、有说服力地传达给你的读者。这听起来简单，但执行起来，却是一门融合了研究、思考、表达和严谨的艺术。别把它想象得有多么高深莫测，它就像是搭一座牢固的房子，需要打好地基，规划好结构，再精雕细琢每一个细节。让我来跟你掰扯掰扯，写好一篇论文，到底需要哪些步骤，.............
  • 问题

    如何把写好的push代码放在阿里云上的移动推送上?

    回答
    .......
  • 问题

    如何写一份能获得商家赞助的好活动策划？

    回答
    如何策划一场让商家心动、乐于赞助的活动？这可不是件简单的“交差”任务，更像是一场精心设计的“求婚”。你需要充分了解你的“潜在赞助商”，然后用他们最喜欢的方式，将你的活动“嫁”出去。下面，我来跟你掰扯掰扯，如何一步步打造一份能打动人心的活动策划。第一步：知己知彼，百战不殆——深度挖掘你的活动价值与商家.............
  • 问题

    如何记得每天上床前写好明天要做的事情？

    回答
    每天睡前，脑袋里总是像走马灯一样，一会儿闪过今天没完成的事，一会儿又冒出明天要操心的任务。可这一旦躺到枕头上，那些零碎的念头就变得模糊不清，到了早上，往往是兵荒马乱，完全不知道从何下手。所以，养成一个睡前习惯，给自己一个“明天功课表”，这事儿可太重要了。它不是什么枯燥的说教，更像是一种给自己放的“小.............

本站所有内容均为互联网搜索引擎提供的公开搜索信息，本站不存储任何数据与内容，任何内容与数据均与本站无关，如有需要请联系相关搜索引擎包括但不限于百度，google,bing,sogou 等

© 2025 tinynews.org All Rights Reserved. 百科问答小站 版权所有

服务条款
联系我们
关于我们
隐私政策
友情链接
知乎
百度问答
搜狐
新浪