kernel-style.md

Kernel-style commits

Imperative, clearly structured commit messages. The subject says what the change does; the body explains what and why.

Subject

  • Imperative mood: "Add feature", not "Added feature" or "Adds feature"
  • Capitalize the first word
  • No trailing period
  • Maximum 50 characters

Some projects use a subsystem prefix (e.g., net/tcp: Fix buffer overflow, auth: Add OIDC provider). Check recent commit subjects to see whether the project follows this convention, and use the same prefix style if so. The prefix and colon count toward the 50-character limit.

Validate the subject with the format script before composing the full message. You'll often need to iterate on the subject a few times to get it under 50 characters — this is a cheap round trip compared to recomposing the whole message:

/path/to/formatting-commits/scripts/format subject "Your subject line here"

Exit 0 means the subject is valid. Exit 1 means it exceeds 50 characters — rephrase rather than truncate.

Body

Explain what changed and why, not how — the diff shows how.

The format script handles body reflow, so you don't need to worry about wrapping. Freely write standard, Markdown-ish commits and it'll handle the rest.

You tend to wrap your own lines incorrectly because you see in tokens, not characters. Always pipe the message through the format script rather than trusting your own line breaks.

Composing and formatting

  1. Draft the subject and iterate with format subject until it fits
  2. Write the full message (subject, blank line, body, blank line, trailers)
  3. Pipe the whole thing through format message, which validates the subject, reflows the body, and passes trailers through unchanged
/path/to/formatting-commits/scripts/format message <<'EOF' | git commit -F -
Add OIDC discovery support

This commit refactors the authentication module to support
multiple identity providers.

- Replace the monolithic auth handler with a provider interface
- Add support for OIDC discovery

Signed-off-by: Name <email>
Fixes: https://todo.sr.ht/~user/tracker/#42
EOF

The format script detects trailers at the end of the message (lines matching Key: value format) and preserves them as-is. Everything between the subject and the trailer block is reflowed as body text.

Amending

  • Message stays accurate: amend without changing the message
  • Message needs updating: compose and format a new message, then amend with the formatted output