Writing Commit Messages That Double as Documentation

说明与用途

糟糕的提交信息会延迟后续调查。作者提出三部分结构（what、why、impact）和提交模板，以加速未来的代码检索。

问题

Bad commit messages make future investigations time‑consuming.

结果

Commit messages that answer what, why, and impact reduce investigation time from 20 minutes to a few seconds when using git blame.

工作流

• 1. Write a 50‑character subject in present tense, e.g., "Add timeout to payment handler".
• 2. Insert a blank line.
• 3. Write a body of up to 72 characters per line, divided into three paragraphs: first – what changed, second – why it changed, third – impact and surprises.
• 4. Use a commit template with prompts for the three sections.
• 5. Avoid the -m flag for non‑trivial commits; open the editor instead.
• 6. Squash work‑in‑progress commits before merging.
• 7. Optionally use AI to draft the what/why/impact message, then review the why.

证据

Bad messages like "fix bug" cost me 20 minutes per investigation months later

来源

The body matters more than the subject line for future archaeology

来源

A good commit has a subject line and a body, separated by a blank line

来源

The first thing is a commit template. Git lets you set one with a config pointing at a text file.

来源

The second thing is banning -m for anything non‑trivial.

来源