---
name: formatting-commits
description: >-
  Formats commit messages by detecting the project's style from recent history.
  ALWAYS read BEFORE committing changes, amending commits, or when the user
  mentions commits, commit messages, conventional commits, or commit formatting,
  regardless of VCS. Also use when writing tag annotations or change
  descriptions.
license: GPL-3.0-or-later
metadata:
  author: Amolith <amolith@secluded.site>
---

Formats commit and change messages. Detects the project's style, then follows
the appropriate conventions for subject, body, and trailers.

## Detecting the style

Look at ~20 recent commit or change subjects. Two patterns to check:

- **Conventional Commits**: subjects match `type:` or `type(scope):` prefixes
  (e.g., `feat:`, `fix(auth):`, `chore:`, `refactor(api):`)
- **Kernel-style**: subjects are plain imperative statements with no type
  prefix (e.g., "Add user authentication", "net: Fix buffer overflow")

If the majority of recent subjects follow one pattern, use that style. If the
history is mixed or the repository has no commits, ask the user.

## Style paths

- **Conventional Commits** → read [conventional-commits.md](references/conventional-commits.md)
- **Kernel-style** → read [kernel-style.md](references/kernel-style.md)

## Trailers

Both styles use trailers. They go after the body, separated by a blank line.
Format: `Key: value`, one per line.

Valid trailer keys for ticket tracking depend on the platform:

- GitHub: Closes, Fixes, Resolves, References
- SourceHut: Closes, Fixes, Implements, References

On the Conventional Commits path, pass trailers as `-T` flags to
`git formatted-commit`. On the kernel-style path, include trailers at the end
of the message before piping through `scripts/format message` — the script
detects and preserves them.