Conventional Commits is a lightweight specification for writing commit messages that are human-readable and machine-processable. Conventional Commits Instead of writing vague messages like "fixed bug" or "updates", this convention provides a rigorous rule set for creating an explicit commit history. This makes it easier to understand what happened in a project and why, and it enables potent automation tools (like automatic changelogs and version bumping). what why 1. Anatomy of a Commit Message A conventional commit message mimics the structure of an email, with a clear header (subject), optional body, and optional footer. <type>[optional scope]: <description>

[optional body]

[optional footer(s)] <type>[optional scope]: <description>

[optional body]

[optional footer(s)] The Header (Required) The first line is the most important. It contains three parts: Type: What kind of change is this? (e.g., feat, fix, chore)
Scope (Optional): What part of the codebase is affected? (e.g., (auth), (checkout))
Description: A short, imperative summary of the change. Type: What kind of change is this? (e.g., feat, fix, chore) Type: feat fix chore Scope (Optional): What part of the codebase is affected? (e.g., (auth), (checkout)) Scope (Optional): (auth) (checkout) Description: A short, imperative summary of the change. Description: The Body (Optional) This provides more context. Use it to explain the "why" behind the change, not just the "how". Example: "The previous regex was causing a memory leak on large inputs. Switched to a stream-based parser." Example: "The previous regex was causing a memory leak on large inputs. Switched to a stream-based parser." Example: The Footer (Optional) Used for referencing issues or indicating breaking changes. Example: Closes #123 or BREAKING CHANGE: API endpoint /users renamed to /profiles Example: Closes #123 or BREAKING CHANGE: API endpoint /users renamed to /profiles Example: Closes #123 BREAKING CHANGE: API endpoint /users renamed to /profiles 2. Commit Types (Cheat Sheet) You only need to memorize a few major types. Type

Meaning

SemVer Correlation

Example



feat

A new feature for the user.

MINOR (1.1.0)

feat(search): add voice search capability



fix

A bug fix for the user.

PATCH (1.0.1)

fix(login): handle null token gracefully



docs

Documentation only changes.

PATCH

docs: update API usage in README



chore

Maintenance changes that don't affect src or test files.

PATCH

chore: upgrade flutter dependencies



style

Code style changes (formatting, missing semi-colons, etc).

PATCH

style: apply dart format



refactor

A code change that neither fixes a bug nor adds a feature.

PATCH

refactor(auth): simplify login logic



test

Adding missing tests or correcting existing tests.

PATCH

test: add unit tests for user_service



perf

A code change that improves performance.

PATCH

perf: optimize image loading in listview



ci

Changes to CI configuration files and scripts.

PATCH

ci: add github actions workflow Type

Meaning

SemVer Correlation

Example



feat

A new feature for the user.

MINOR (1.1.0)

feat(search): add voice search capability



fix

A bug fix for the user.

PATCH (1.0.1)

fix(login): handle null token gracefully



docs

Documentation only changes.

PATCH

docs: update API usage in README



chore

Maintenance changes that don't affect src or test files.

PATCH

chore: upgrade flutter dependencies



style

Code style changes (formatting, missing semi-colons, etc).

PATCH

style: apply dart format



refactor

A code change that neither fixes a bug nor adds a feature.

PATCH

refactor(auth): simplify login logic



test

Adding missing tests or correcting existing tests.

PATCH

test: add unit tests for user_service



perf

A code change that improves performance.

PATCH

perf: optimize image loading in listview



ci

Changes to CI configuration files and scripts.

PATCH

ci: add github actions workflow Type

Meaning

SemVer Correlation

Example Type Type Meaning Meaning SemVer Correlation SemVer Correlation Example Example feat

A new feature for the user.

MINOR (1.1.0)

feat(search): add voice search capability feat feat feat A new feature for the user. A new feature for the user. MINOR (1.1.0) MINOR (1.1.0) MINOR 1.1.0 feat(search): add voice search capability feat(search): add voice search capability feat(search): add voice search capability fix

A bug fix for the user.

PATCH (1.0.1)

fix(login): handle null token gracefully fix fix fix A bug fix for the user. A bug fix for the user. PATCH (1.0.1) PATCH (1.0.1) PATCH 1.0.1 fix(login): handle null token gracefully fix(login): handle null token gracefully fix(login): handle null token gracefully docs

Documentation only changes.

PATCH

docs: update API usage in README docs docs docs Documentation only changes. Documentation only changes. PATCH PATCH PATCH docs: update API usage in README docs: update API usage in README docs: update API usage in README chore

Maintenance changes that don't affect src or test files.

PATCH

chore: upgrade flutter dependencies chore chore chore Maintenance changes that don't affect src or test files. Maintenance changes that don't affect src or test files. PATCH PATCH PATCH chore: upgrade flutter dependencies chore: upgrade flutter dependencies chore: upgrade flutter dependencies style

Code style changes (formatting, missing semi-colons, etc).

PATCH

style: apply dart format style style style Code style changes (formatting, missing semi-colons, etc). Code style changes (formatting, missing semi-colons, etc). PATCH PATCH PATCH style: apply dart format style: apply dart format style: apply dart format refactor

A code change that neither fixes a bug nor adds a feature.

PATCH

refactor(auth): simplify login logic refactor refactor refactor A code change that neither fixes a bug nor adds a feature. A code change that neither fixes a bug nor adds a feature. PATCH PATCH PATCH refactor(auth): simplify login logic refactor(auth): simplify login logic refactor(auth): simplify login logic test

Adding missing tests or correcting existing tests.

PATCH

test: add unit tests for user_service test test test Adding missing tests or correcting existing tests. Adding missing tests or correcting existing tests. PATCH PATCH PATCH test: add unit tests for user_service test: add unit tests for user_service test: add unit tests for user_service perf

A code change that improves performance.

PATCH

perf: optimize image loading in listview perf perf perf A code change that improves performance. A code change that improves performance. PATCH PATCH PATCH perf: optimize image loading in listview perf: optimize image loading in listview perf: optimize image loading in listview ci

Changes to CI configuration files and scripts.

PATCH

ci: add github actions workflow ci ci ci Changes to CI configuration files and scripts. Changes to CI configuration files and scripts. PATCH PATCH PATCH ci: add github actions workflow ci: add github actions workflow ci: add github actions workflow 3. Practical Examples ✨ Feature (feat) feat Used when adding new functionality. feat(cart): add "Undo" button after removing item

Allows users to quickly recover an item if they accidentally deleted it. feat(cart): add "Undo" button after removing item

Allows users to quickly recover an item if they accidentally deleted it. 🐛 Bug Fix (fix) fix Used when fixing a bug. fix(navigation): prevent double-pushing the home screen

The "Home" button was pushing a new route instead of popping to root.
This caused the navigation stack to grow indefinitely.

Closes #42 fix(navigation): prevent double-pushing the home screen

The "Home" button was pushing a new route instead of popping to root.
This caused the navigation stack to grow indefinitely.

Closes #42 💥 Breaking Change (!) ! There are two ways to mark a breaking change (which triggers a MAJOR version bump): MAJOR Using a ! after the type/scope.
Adding a BREAKING CHANGE: footer. Using a ! after the type/scope. ! Adding a BREAKING CHANGE: footer. BREAKING CHANGE: Example 1 (Using !): Example 1 (Using ! feat(api)!: remove support for XML responses

We now strictly return JSON. XML parsers will fail. feat(api)!: remove support for XML responses

We now strictly return JSON. XML parsers will fail. Example 2 (Using Footer): Example 2 (Using Footer): chore: drop support for Node 12

BREAKING CHANGE: The project now requires Node 14 or higher due to new crypto dependencies. chore: drop support for Node 12

BREAKING CHANGE: The project now requires Node 14 or higher due to new crypto dependencies. 4. Good vs. Bad Examples See the difference between a messy history and a clean one. ❌ Bad / Vague

✅ Good / Conventional

Why it's better



fixed it

fix(login): handle timeout error

Tells us what was fixed and where.



added stuff

feat(profile): add user avatar upload

Clearly states the new feature.



wip

(Don't commit WIPs to main)

Keep history clean. Use git rebase to squash WIPs.



changed color

style(theme): update primary button color

Categorizes the change as stylistic.



API change

feat(api)!: rename getAll to fetchAll

The ! warns everyone this is a BREAKING change. ❌ Bad / Vague

✅ Good / Conventional

Why it's better



fixed it

fix(login): handle timeout error

Tells us what was fixed and where.



added stuff

feat(profile): add user avatar upload

Clearly states the new feature.



wip

(Don't commit WIPs to main)

Keep history clean. Use git rebase to squash WIPs.



changed color

style(theme): update primary button color

Categorizes the change as stylistic.



API change

feat(api)!: rename getAll to fetchAll

The ! warns everyone this is a BREAKING change. ❌ Bad / Vague

✅ Good / Conventional

Why it's better ❌ Bad / Vague ❌ Bad / Vague ✅ Good / Conventional ✅ Good / Conventional Why it's better Why it's better fixed it

fix(login): handle timeout error

Tells us what was fixed and where. fixed it fixed it fixed it fix(login): handle timeout error fix(login): handle timeout error fix(login): handle timeout error Tells us what was fixed and where. Tells us what was fixed and where. what where added stuff

feat(profile): add user avatar upload

Clearly states the new feature. added stuff added stuff added stuff feat(profile): add user avatar upload feat(profile): add user avatar upload feat(profile): add user avatar upload Clearly states the new feature. Clearly states the new feature. wip

(Don't commit WIPs to main)

Keep history clean. Use git rebase to squash WIPs. wip wip wip (Don't commit WIPs to main) (Don't commit WIPs to main) (Don't commit WIPs to main) Keep history clean. Use git rebase to squash WIPs. Keep history clean. Use git rebase to squash WIPs. git rebase changed color

style(theme): update primary button color

Categorizes the change as stylistic. changed color changed color changed color style(theme): update primary button color style(theme): update primary button color style(theme): update primary button color Categorizes the change as stylistic. Categorizes the change as stylistic. API change

feat(api)!: rename getAll to fetchAll

The ! warns everyone this is a BREAKING change. API change API change API change feat(api)!: rename getAll to fetchAll feat(api)!: rename getAll to fetchAll feat(api)!: rename getAll to fetchAll The ! warns everyone this is a BREAKING change. The ! warns everyone this is a BREAKING change. ! 5. Why Should You Care? Automated Changelogs: You can use tools to generate standard changelogs automatically. No more manual writing!
Semantic Versioning: Tools can look at your commit history (feat, fix, BREAKING) and determine if the next version should be 1.0.1, 1.1.0, or 2.0.0 automatically.
Better Collaboration: When reviewing history (e.g., git log), it's immediately obvious what happened.

Scan for fix to see recent bug patches.
Scan for feat to see what's new.


Discipline: It forces you to think about the nature of your change. If you can't categorize it, your commit might be doing too many things at once. Automated Changelogs: You can use tools to generate standard changelogs automatically. No more manual writing! Automated Changelogs: Semantic Versioning: Tools can look at your commit history (feat, fix, BREAKING) and determine if the next version should be 1.0.1, 1.1.0, or 2.0.0 automatically. Semantic Versioning: feat fix BREAKING 1.0.1 1.1.0 2.0.0 Better Collaboration: When reviewing history (e.g., git log), it's immediately obvious what happened.

Scan for fix to see recent bug patches.
Scan for feat to see what's new. Better Collaboration: git log Scan for fix to see recent bug patches.
Scan for feat to see what's new. Scan for fix to see recent bug patches. Scan for fix Scan for feat to see what's new. Scan for feat Discipline: It forces you to think about the nature of your change. If you can't categorize it, your commit might be doing too many things at once. Discipline: nature 6. FAQ Q: What if I accidentally use the wrong type? Q: What if I accidentally use the wrong type? A: If you haven't pushed yet, use git commit --amend. If you have pushed to a shared branch, it’s usually okay to leave it unless your team relies heavily on automated releases. git commit --amend Q: Can I use my own types? Q: Can I use my own types? A: Yes! The spec is flexible. Some teams use build:, revert:, or even emojis. Just be consistent. build: revert: Q: Should I use lower case or Title Case? Q: Should I use lower case or Title Case? A: The spec allows either, but lower case is the most common convention in the industry (e.g., feat: not Feat:). lower case feat: Feat: Q: What if a commit does multiple things? Q: What if a commit does multiple things? A: That's a sign you should split it! A commit should ideally do one thing. If you fixed a bug AND added a feature, split it into two commits: fix: ... and feat: .... fix: ... feat: ... Q: How do I handle revert commits? Q: How do I handle revert commits? A: The convention suggests using a revert: type. The header should contain the header of the specific commit being reverted, and the body should contain This reverts commit <hash>.. revert: This reverts commit <hash>. Q: Is there a character limit for the header? Q: Is there a character limit for the header? A: It is meant to be a summary. A good rule of thumb is to keep it under 50 characters where possible, and strictly under 72 characters to avoid wrapping in various git tools. 50 characters 72 characters Q: How granular should the scope be? Q: How granular should the scope be? A: Scopes should be distinct modules or features (e.g., auth, payment, ui). Avoid using precise filenames (like user_service.dart) as scopes; stick to the "concept" of the component. auth payment ui user_service.dart Reference(s) Conventional Commits Conventional Commits Conventional Commits

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Conventional Commits: A Guide to Writing Structured Git Commit Messages

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Less Data, Same LLM Performance? UGA Says Yes

This Cheap OTG Hack Made My Phone Feel Like a PC

MacBook Neo Review: Apple’s Budget Laptop Comes With Big Tradeoffs

Conventional Commit Specification Guidelines: What You Need to Know

10 GitHub Repositories to Follow

3 Easy Steps to Change Main Git Branch on Heroku

Less Data, Same LLM Performance? UGA Says Yes

This Cheap OTG Hack Made My Phone Feel Like a PC

MacBook Neo Review: Apple’s Budget Laptop Comes With Big Tradeoffs

Conventional Commit Specification Guidelines: What You Need to Know

10 GitHub Repositories to Follow

3 Easy Steps to Change Main Git Branch on Heroku

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps