1# Kernel-style commits
2
3Imperative, clearly structured commit messages. The subject says what the
4change does; the body explains what and why.
5
6## Subject
7
8- Imperative mood: "Add feature", not "Added feature" or "Adds feature"
9- Capitalize the first word
10- No trailing period
11- Maximum 50 characters
12
13Some projects use a subsystem prefix (e.g., `net/tcp: Fix buffer overflow`,
14`auth: Add OIDC provider`). Check recent commit subjects to see whether the
15project follows this convention, and use the same prefix style if so. The
16prefix and colon count toward the 50-character limit.
17
18Validate the subject with the format script before composing the full message.
19You'll often need to iterate on the subject a few times to get it under 50
20characters — this is a cheap round trip compared to recomposing the whole
21message:
22
23```
24/path/to/formatting-commits/scripts/format subject "Your subject line here"
25```
26
27Exit 0 means the subject is valid. Exit 1 means it exceeds 50 characters —
28rephrase rather than truncate.
29
30## Body
31
32Explain _what_ changed and _why_, not _how_ — the diff shows how.
33
34The format script handles body reflow, so you don't need to worry about
35wrapping. Freely write standard, Markdown-ish commits and it'll handle the rest.
36
37You tend to wrap your own lines incorrectly because you see in tokens, not
38characters. Always pipe the message through the format script rather than
39trusting your own line breaks.
40
41## Composing and formatting
42
431. Draft the subject and iterate with `format subject` until it fits
442. Write the full message (subject, blank line, body, blank line, trailers)
453. Pipe the whole thing through `format message`, which validates the subject,
46 reflows the body, and passes trailers through unchanged
47
48```bash
49/path/to/formatting-commits/scripts/format message <<'EOF' | git commit -F -
50Add OIDC discovery support
51
52This commit refactors the authentication module to support
53multiple identity providers.
54
55- Replace the monolithic auth handler with a provider interface
56- Add support for OIDC discovery
57
58Signed-off-by: Name <email>
59Fixes: https://todo.sr.ht/~user/tracker/#42
60EOF
61```
62
63The format script detects trailers at the end of the message (lines matching
64`Key: value` format) and preserves them as-is. Everything between the subject
65and the trailer block is reflowed as body text.
66
67## Amending
68
69- **Message stays accurate**: amend without changing the message
70- **Message needs updating**: compose and format a new message, then amend
71 with the formatted output