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