Git Best Practices for Developers

Chapter 1 · Practice 2 of 4

Write a short summary line, a blank line, then explain why

From Commits and commit messages

Why it matters

A commit message is read far more often than it is written: in git log --oneline, in patches, in blame views and in many tools. The Git documentation recommends a simple shape.

  1. One short summary line, no more than 50 characters.
  2. A blank line. Git treats the text up to the first blank line as the commit title.
  3. A fuller description, wrapped at about 72 characters.

Write the summary in the imperative, like Add retry to payment webhook, which reads naturally as "this commit will add...".

Use the body to explain why the change was needed and anything surprising about it. The diff already shows what changed.

Example

Code
Add retry to payment webhook handler

The provider sometimes returns 503 during deploys, and we were
dropping those events. Retry up to 3 times with backoff before
marking the event as failed.

Refs: #482