1---
 2name: formatting-commits
 3description: >-
 4  Formats commit messages by detecting the project's style from recent history.
 5  ALWAYS read BEFORE committing changes, amending commits, or when the user
 6  mentions commits, commit messages, conventional commits, or commit formatting,
 7  regardless of VCS. Also use when writing tag annotations or change
 8  descriptions.
 9license: GPL-3.0-or-later
10metadata:
11  author: Amolith <amolith@secluded.site>
12---
13
14Formats commit and change messages. Detects the project's style, then follows
15the appropriate conventions for subject, body, and trailers.
16
17## Detecting the style
18
19Look at ~20 recent commit or change subjects. Two patterns to check:
20
21- **Conventional Commits**: subjects match `type:` or `type(scope):` prefixes
22  (e.g., `feat:`, `fix(auth):`, `chore:`, `refactor(api):`)
23- **Kernel-style**: subjects are plain imperative statements with no type
24  prefix (e.g., "Add user authentication", "net: Fix buffer overflow")
25
26If the majority of recent subjects follow one pattern, use that style. If the
27history is mixed or the repository has no commits, ask the user.
28
29## Style paths
30
31- **Conventional Commits** → read [conventional-commits.md](references/conventional-commits.md)
32- **Kernel-style** → read [kernel-style.md](references/kernel-style.md)
33
34## Trailers
35
36Both styles use trailers. They go after the body, separated by a blank line.
37Format: `Key: value`, one per line.
38
39Valid trailer keys for ticket tracking depend on the platform:
40
41- GitHub: Closes, Fixes, Resolves, References
42- SourceHut: Closes, Fixes, Implements, References
43
44On the Conventional Commits path, pass trailers as `-T` flags to
45`git formatted-commit`. On the kernel-style path, include trailers at the end
46of the message before piping through `scripts/format message` — the script
47detects and preserves them.