Crafting effective commit messages is a hallmark of experienced developers. Embracing the Conventional Commits specification stands as a beacon for structuring commit messages. It’s not just a guideline; it’s a pathway to a clearer commit history that harmonizes with Semantic Versioning (SemVer).
What are Conventional Commits?
Conventional Commits offer a lightweight yet powerful framework for organizing commit messages. By categorizing changes into distinct types like features, fixes, and breaking changes, it sets a gold standard for clarity and consistency and aligns with Semantic Versioning (SemVer) by categorizing changes into features, fixes, and breaking changes.
The Anatomy of a Great Commit Message
When making commits, please use the conventional commit format, which typically follows the pattern of <type>: <description>.
A commit message should follow this structure:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
type: type of commit
scope: Short description of a section of the codebase enclosed in parenthesis followed by a colon and a space. Messages tend to be in the present and imperative.
description: Short description of the code changes
body: A longer description of the commit, providing additional context about the changes.
Must be placed one empty line after the description.
footer: Fixes issue #3 //example
The footer should only contain additional issue references about the changes.
Examples:
A commit I made to solve an issue.
feat(homepage): Add carousel feature to showcase testimonials
Implemented a carousel component on the homepage
Added client testimonials section for improved user engagement
Fixes #12
More examples:
- feat: Add new rating component
- fix: Resolve issue with city search feature
- docs: Update README with new contribution guidelines
Types of Commits
In addition to the classic fixand feat, we've got a whole buffet of commit types. It's like choosing toppings for your commit pizza:
-
build: Changes related to build processes or tools. -
chore: Regular maintenance or administrative tasks. -
ci: Updates to the continuous integration setup. -
docs: Documentation-related changes. -
style: Changes that do not affect the code’s functionality (e.g., formatting). -
refactor: Code modifications without changing its behavior. -
perf: Performance improvements. -
test: Adding or modifying tests.
You can use these types to categorize your commits according to their nature. This helps maintain consistency in commit messages and aids in better organization of changes in the project history.
Footnote
For more information on Conventional Commits, visit Conventional Commits Specification.
Top comments (40)
Thanks for sharing
I use this tool: github.com/streamich/git-cz, which is a CLI-guided tool to create awesome commit messages as well.
Very cool! Thanks for sharing!
this is so cool!
While the intent is good and for the most part this guideline is ok, I really do not like commit messages tell me what was done to the code. I can see that, when I look at the code. I want to know why this was changed. So please do not tell me, that you "changed the build process". I can see that. What I cannot see, by looking at the code is why we changed the build process. A message like "build process was taking 20 min, now takes 2" with some explanation in the body is way better. "Resolve issue with search feature" is also something, that I can see by
git show --name-onlypretty quickly. But what was the issue?"Add a new rating component". Yes... I can see that you inserted a new file in folder 'rating-components' that pretty much gave it away already. What rating component? Is it replacing the old one? Is it country specific? Gender specific? (Don't flame me for this, that shit happens in real life)
Botton line: Having a what is better than nothing (aka 'Did stuff'), but having a why is even better.
Why > What > Nothing.
Good day Christian Baer, what if the product is +100K line of code, don't you think that 'What' is the most important thing in the commit message than 'why', otherwise whoever reading/reviewing might get lost.
For the 'Why' it's even more important, cause without it then it's pointless to do write whatever code is, but in context of the message commit, I prefer 'what' over than 'why' which could be described on the issue/ticket itself. And leave the commit message to 'what' is actually changed to achieve the task (that has the why)
Funny sidemark: we currently use a template that features both why and how:
In my opinion, I think one can use the what as description and then include the why in the body of the commit. that way, both are fulfilled.
Why would one pull request encompass 100k+ lines of code exactly?
Nice post, thanks for sharing.
Also I think it worth to think about what we've done when trying to write the description.
For example there are times when we fix a bug by changing something in x.ts file.
Appropriate commit message would describe what issue we have resolved not what we changed in x.ts.
BTW thats my idea and I had better experience during reviewing more meaningful commits and don't know if it is a rule or something.
Thank you again.
Also important to mention: Commit messages tend to be in the present and imperative.
E.g: Implement search feature.
Excellent post! The online tool that we use in the company where I work and has helped us with the commits is: commitlint.io/
Thanks for sharing! Would like to share this tool github.com/commitizen-tools/commit... which can help creating commit based on different rules (including convention commit)
I tend to use feature branches so the scope part of the commit message is usually obvious based on that. Other than that I would steer towards this format as much as possible
Thanks for sharing ! I'll be sure to make my commit messages more precise.
I've been tossing a gitmoji at the beginning of commit messages these days. It offers similar categorization and makes it simple to see the intention of a commit at a glance.
gitmoji.dev/
Thank you, this has been very helpful!