Conventional Commit Helper: Build Properly Formatted Commit Messages
Build commit messages following the Conventional Commits specification. Select type, scope, and write a description to generate a perfectly formatted message.
Try the free online tool
Runs entirely in your browser — no signup, no uploads.
Git commit messages are the primary documentation of how a codebase evolves over time. A well-written commit history answers the questions 'what changed' and 'why' for every modification in the project. Unfortunately, most commit histories are filled with messages like 'fix', 'update', 'wip', and 'asdf' that tell future readers nothing about the intent or impact of the change. Conventional Commits is a specification that brings structure and meaning to commit messages.
The Conventional Commits specification defines a simple format: a type prefix (feat, fix, docs, chore, refactor, test, style, perf, ci, build), an optional scope in parentheses describing what part of the codebase changed, a short description, and optionally a body and footer for additional context. Tooling like semantic-release, standard-version, and release-please can parse this structured format to automatically determine version bumps (MAJOR for breaking changes, MINOR for features, PATCH for fixes) and generate changelogs, eliminating the manual overhead of versioning and release notes.
This helper guides you through composing a valid Conventional Commit message step by step: select the type from the standard vocabulary, optionally add a scope, write a short imperative description, add a body for complex changes, and mark breaking changes. The tool assembles the final message in real time and provides a copy-ready output formatted exactly to the specification.
What Is the Conventional Commits Specification?
Conventional Commits is a lightweight convention on top of commit messages that provides a machine-readable structure for communicating the nature of changes. The full specification is maintained at conventionalcommits.org and is versioned independently. It was created by community members involved in Angular's commit message guidelines and has since been adopted by thousands of open-source projects.
The core format is: '<type>[optional scope]: <description>' followed by an optional body after a blank line and optional footer sections after another blank line. The type is one of a defined vocabulary. The description is a short imperative summary (write 'add feature' not 'added feature' or 'adds feature'). Breaking changes are indicated by appending '!' after the type/scope or by including a 'BREAKING CHANGE:' footer.
The specification maps directly to Semantic Versioning: commits of type 'feat' trigger a MINOR version bump, commits of type 'fix' trigger a PATCH bump, and commits with a breaking change marker trigger a MAJOR bump. This mapping enables fully automated versioning and changelog generation in a release pipeline.
How to Use This Tool
Building a conforming commit message takes just a few fields:
- 1
Select the commit type
Choose from the type dropdown: feat (new feature), fix (bug fix), docs (documentation), style (formatting), refactor (no behavior change), test (adding tests), chore (maintenance), perf (performance improvement), ci (CI/CD changes), or build (build system changes).
- 2
Add a scope (optional)
Type a scope in the scope field to identify which component or area of the codebase the change affects. Scopes are typically module names, file paths, or feature area names like 'auth', 'api', 'ui', or 'database'.
- 3
Write the description
Enter a short, imperative-tense description of the change in the description field. Keep it under 72 characters. Use the imperative mood: 'add', 'remove', 'update', 'fix' — not 'added', 'removes', or 'updating'.
- 4
Add body and breaking change info
For complex changes, add a body explaining the motivation and context. If the change breaks backward compatibility, check the Breaking Change checkbox and describe what broke and how consumers should migrate.
- 5
Copy and commit
Click Copy to capture the formatted message and paste it into your git commit command: 'git commit -m "feat(auth): add OAuth2 login support"' or paste it into your editor when running 'git commit' without -m.
Common Use Cases
Conventional Commits provides the most value in contexts where commit history is consumed programmatically or by a wider audience:
- Open-source library maintainers using semantic-release to automate npm package version bumps and GitHub release notes from commit messages
- Monorepo projects using tools like Nx, Lerna, or Changesets that parse commit messages to determine which packages were affected and need version updates
- Team development workflows where a shared commit convention makes code review more efficient and git log more informative for everyone
- CI/CD pipelines that gate merges on commit message format compliance using tools like commitlint to enforce the specification automatically
- Projects that generate a CHANGELOG.md automatically using standard-version or release-please so every release has human-readable documentation of what changed
Tips and Best Practices
The Conventional Commits format is only as useful as its consistent adoption. These practices help a team get maximum value:
- Install commitlint with a commitlint.config.js in your repository and add it as a Git hook via husky. This enforces the format on every commit, ensuring no non-conforming messages slip through.
- Keep descriptions short and in the imperative mood. 'add user registration endpoint' is good; 'added the new user registration API endpoint that handles both email and OAuth signups' is too long for the first line.
- Use the body section for the 'why' of a change rather than the 'what'. The diff already shows what changed. The body should explain the business reason, the tradeoff made, or the issue being resolved.
- Scope names should be consistent within your project. Agree on a scope vocabulary (module names, area names) as a team and document it. Inconsistent scopes reduce the value of automated changelog grouping.
- For pull request workflows, squash commits before merging and write the squash commit message in Conventional Commits format. This keeps the main branch history clean and makes automated tooling reliable.
Frequently Asked Questions
What are the standard Conventional Commit types?
The specification defines: feat (new feature that adds functionality), fix (bug fix), docs (documentation-only changes), style (formatting, missing semicolons — no logic change), refactor (code change that neither fixes a bug nor adds a feature), test (adding or correcting tests), chore (maintenance tasks like updating dependencies), perf (performance improvement), ci (CI configuration changes), and build (build system or external dependency changes).
How do I indicate a breaking change in a commit message?
Add an exclamation mark after the type and scope: 'feat(api)!: remove deprecated v1 endpoints'. Alternatively, add a 'BREAKING CHANGE: description' footer after the commit body. Either approach triggers a MAJOR version bump in semantic-release. Using both the '!' marker and the footer is also valid and provides more documentation.
Is the scope field required?
No. The scope is optional in the specification. When present it narrows the context of the change to a specific component, module, or area of the codebase. When omitted the commit is understood to affect the project broadly or the change does not fit neatly into one area. Many teams use scope consistently; others omit it for simplicity.
Does Conventional Commits work with all Git hosting platforms?
Yes. Conventional Commits is just a formatting convention for commit message text — it works with any Git workflow on GitHub, GitLab, Bitbucket, Azure DevOps, or any other platform. The automated tooling (semantic-release, release-please, standard-version) runs in your CI/CD pipeline independent of the hosting platform.
How does semantic-release use Conventional Commits to determine versions?
semantic-release parses commit messages since the last release tag. Any 'fix' type commit triggers a PATCH release (1.0.0 -> 1.0.1). Any 'feat' type commit triggers a MINOR release (1.0.0 -> 1.1.0). Any commit with a breaking change marker triggers a MAJOR release (1.0.0 -> 2.0.0). Commits of other types (docs, chore, style) do not trigger any release.
Can I use Conventional Commits in a personal project?
Absolutely. Even without automated tooling the structured format makes the project's git log far more readable and searchable. Running 'git log --oneline' on a project with Conventional Commits immediately shows which commits added features, which fixed bugs, and which were maintenance. The discipline also builds good habits that transfer directly to team and open-source work.
How do I enforce Conventional Commits in my team?
Install commitlint ('npm install --save-dev @commitlint/cli @commitlint/config-conventional') with a config file ('echo module.exports = {extends: ["@commitlint/config-conventional"]} > commitlint.config.js') and add it as a commit-msg Git hook using husky. Every commit message is then automatically validated against the specification before the commit is accepted.
Ready to use this tool?
Free, instant, no account required. Runs entirely in your browser.