| name | conventional-commit |
| description | Workflow for generating conventional commit messages following the Conventional Commits specification. MUST be invoked every time a commit is created. Guides construction of standardized commit messages with correct type, scope, description, body, and footer.
|
| triggers | ["on_commit"] |
Conventional Commit
Commit Message Structure
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Types
| Type | When to use |
|---|
feat | A new feature |
fix | A bug fix |
docs | Documentation changes, no code |
style | Formatting, missing semicolons, etc. (no logic change) |
refactor | Code change that is neither a fix nor a feature |
perf | Performance improvement |
test | Adding or correcting tests |
ci | CI configuration changes |
chore | Maintenance tasks (updating deps, tooling, etc.) |
revert | Reverts a previous commit |
Append ! after the type/scope to signal a breaking change: feat!: or feat(api)!:
When a change breaks existing behavior, both markers are mandatory: the ! suffix on the type
and the BREAKING CHANGE: footer. They always appear together — never one without the other.
Scope
Optional. Use the name of the area affected, e.g., segment, cache, config, ui.
Omit when the change is truly cross-cutting.
Description
- Required. One short imperative sentence, no period at the end. The full header line (type +
scope + description) must be 72 characters or fewer. Aim for 50 characters or fewer for
the description itself — this almost always keeps the full header within budget regardless
of type and scope length.
- Use the imperative mood: "add", not "added" or "adds". Never past tense or present-third-person:
✗
added, fixed, bumped, implemented → ✓ add, fix, bump, implement.
- Never mirror the input's phrasing. If the request uses past-tense words (
updated, added,
bumped, was removed, got regenerated), convert them to imperative before writing the
description: update, add, bump, remove, regenerate.
Body
Optional. Add context about why the change was made, not what. The diff shows that.
Wrap at 72 characters.
Footer
Use for:
BREAKING CHANGE: <description> (required when ! is used; explains the break).- Issue references:
Closes #123, Fixes #456.
- Co-authors:
Co-Authored-By: Name <email>.
Workflow
- Run
git status to review changed files.
- Run
git diff and git diff --cached to inspect staged and unstaged changes.
- Identify the type from the table above. Ask yourself: does this change remove, rename, or
alter existing behavior that callers depend on? If yes → it is a breaking change: use
!
after the type/scope and add a BREAKING CHANGE: footer. Both markers are always required
together.
- Identify the scope from the files/area changed.
- Write a short description in the imperative mood.
- Add a body if the why needs explanation.
- Add a footer for breaking changes or issue references.
- Stage the relevant files explicitly (avoid
git add -A).
- Commit with a message that preserves multi-line formatting when body/footer are present.
Examples
feat(segment): add Ramadan segment with Aladhan API
fix(cache): always store mod time
docs(readme): update installation instructions
refactor(config): simplify option parsing logic
chore(deps): bump github.com/shirou/gopsutil/v4
feat(segment)!: rename template property StartTime to Start
BREAKING CHANGE: template strings using .StartTime must be updated to .Start
Validation Checklist
