# 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

```bash
/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