Writing Commit Messages That Double as Documentation

Описание и применение

Плохие сообщения коммитов затрудняют поиск изменений. Автор предлагает структуру из трёх частей (что, почему, влияние) и шаблон коммита, чтобы ускорить будущие расследования.

Задача

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.

Источник