Why I still hand write my commit messages

为什么我依然坚持手写提交信息 (Commit Messages)

For over a decade, I’ve been a proponent of writing detailed Git commit messages. I find it a valuable use of my time, and continue to double down on it, even in a world where you can get a Large Language Model (LLM) to write it for you.

十多年来，我一直主张编写详细的 Git 提交信息。我发现这是一种非常值得投入时间的工作，即便在如今可以通过大语言模型（LLM）代劳的时代，我依然坚持这样做。

In the past, I’ve written about at least 89 strong feelings I have about Git commits, so I’m naturally biased to the benefit of commit messages, but why does this still hold in the current age, where a lot of people are delegating that to an AI agent, if at all?

过去，我曾写过至少 89 条关于 Git 提交的强烈感受，因此我自然倾向于认可提交信息的好处。但在如今这个许多人甚至将此任务完全委托给 AI 代理的时代，为什么这种做法依然有意义呢？

“Why” is better than “what”

“为什么”比“是什么”更重要

One of the most important things a commit message should explain is why you’re making a given change. Chris Beams’ post about writing commit messages is probably one of the more cited blog posts of all time, and is a great resource on this and a number of other important pieces to remember when writing a commit message.

提交信息最重要的一点是解释你为什么要进行某项更改。Chris Beams 关于编写提交信息的文章可能是史上被引用最多的博客文章之一，它不仅涵盖了这一点，还提供了许多编写提交信息时需要记住的重要建议。

Unfortunately a lot of humans, and by extension LLMs, still continue to re-explain what has changed in a given commit. Generally, the “what” is clear, as you can see it in the diff itself. Although not all code is “self-documenting”, you can generally see “what” is changed by looking at a commit’s diff.

遗憾的是，许多人（进而延伸到 LLM）依然在重复解释某次提交中“改变了什么”。通常，“是什么”是很清楚的，因为你可以在 diff（差异对比）中直接看到。虽然并非所有代码都能“自解释”，但通过查看提交的 diff，你通常能看出“改变了什么”。

If you don’t document why you’re making the change, you’re missing out on really important context. Some other areas I focus on calling out:

• if this is a prerequisite/prefactor for other changes
• if this is a bug that this fix is resolving (not only referencing issues/JIRA tickets, but also any examples or error messages of note)
• whether this has crept in due to a gap in my own review/implementation
• it’s only a blame culture when it’s me, otherwise I’ll use we - i.e. I’d missed this from $sha
• if there were any trade-offs, such as why we’re executing an external command, instead of implementing a Typescript-based parser

如果你不记录为什么要进行更改，就会丢失非常重要的上下文。我还会重点标注以下内容：

• 这是否是其他更改的先决条件或重构准备；
• 这是否是修复某个 Bug（不仅是引用 Issue/JIRA 工单，还包括任何值得注意的示例或错误信息）；
• 这是否是因为我自己的审查或实现疏忽而引入的；
• 只有当错误是我自己造成时才进行自我批评，否则我会使用“我们”——例如：我在 $sha 中遗漏了这一点；
• 是否存在权衡，例如为什么我们执行外部命令，而不是实现一个基于 TypeScript 的解析器。

In each of these cases, it helps provide more insight into what led to the change and why we’re doing it.

在上述每种情况下，这都有助于提供更多洞察，说明是什么导致了这次更改，以及我们为什么要这样做。

Can I explain it?

我能解释清楚吗？

The process of writing the commit message is also greatly helpful in determining whether I do actually understand the changes I’ve just made. As we heard last week at GopherCon UK, a study in 2014 shows that you are more likely to retain knowledge if you are expected to teach it.

编写提交信息的过程对于判断我是否真正理解刚刚所做的更改非常有帮助。正如上周在 GopherCon UK 上听到的那样，2014 年的一项研究表明，如果你预期要教别人，你更有可能记住知识。

By making sure that I need to explain why a given commit’s changes are necessary, I can make sure I do actually understand what I’m about to commit, and how I’d explain it in my own words. I’ll very often find that - even with changes I’ve fully authored myself - as I’m going to explain it, I don’t necessarily agree with a choice I’ve made, or now that I’ve stepped back to review the changes, I can see a better option.

通过确保我需要解释某次提交的更改为何必要，我可以确认自己确实理解了即将提交的内容，以及如何用自己的话将其表达出来。我经常发现，即使是完全由我编写的代码，在尝试解释时，我也不一定认同自己当初的选择；或者当我退后一步重新审视这些更改时，我能发现更好的方案。

I’m the author now

我现在是作者

In the case I’m working with some AI-assisted code, I may not have necessarily been the driver of the changes or making a lot of the decisions that were made. By having to explain the choices in the commit message, I’m not only working out why the decisions were made, but taking full ownership of the changes. (regardless of whether you do this or not, if you’ve committed it, it’s your responsibility!)

如果我是在使用 AI 辅助编写代码，我可能并不一定是这些更改的驱动者，也没有做出大部分决策。通过在提交信息中解释这些选择，我不仅理清了决策背后的原因，还对这些更改承担了全部责任。（无论你是否这样做，只要是你提交的，责任就在你！）

AI can’t replicate my taste (yet?)

AI（目前）还无法复制我的品味

It wasn’t surprising that these commits were better, but not quite my writing style. That’s absolutely OK - I don’t actually want an AI to be able to write like I do. But it is a nice point where in projects I’m not as bothered about writing the perfect commit message, I can get something reasonable that sounds a bit more like what I’d want out of it.

这些 AI 生成的提交信息更好并不令人惊讶，但它们并不完全符合我的写作风格。这完全没问题——我其实并不希望 AI 能写得和我一样。但在那些我不太在意编写完美提交信息的项目中，这确实是一个不错的选择，我可以得到一些听起来更符合我预期的合理内容。

I enjoy documenting

我享受记录的过程

I’ve had an affinity for writing documentation for some time. Some of it is down to my familiarity with writing as a form of blogumentation, how it helps my neurodiverse brain, but also because I see a tonne of value from better documentation.

我一直很喜欢编写文档。部分原因是我习惯将写作作为一种“博客式文档”（blogumentation）的形式，这有助于我的神经多样性大脑思考，同时也因为我看到了更好的文档所带来的巨大价值。

I’m not forcing you

我不会强迫你

To be very clear, this is how I work and how I want to handle this myself. Even in the projects I run, I don’t enforce this on anyone - I’ve learned over the years it’s not worth it to try and require it.

需要明确的是，这是我的工作方式，也是我希望处理问题的方式。即使在我负责的项目中，我也不会强迫任何人这样做——多年来我学到的一点是，试图强制要求这些并不值得。