When it comes to version control, Git is a very effective tool. However, like any other tool you have to use it the right way to get the most out of it. There are different aspects that you need to take into consideration. This article focuses on how to write effective Git commit messages following the Conventional Commits specification. It outlines the fundamentals to help you create clear, informative, and standardized commit messages.
How does a good commit message look?
The purpose of sending a message is to communicate. For communication to be effective, the receiver has to clearly understand what the sender of the message is trying to tell them. Thus you need to provide the context and adequate information. Based on this, a good commit message should convey the following:
1. Type (mandatory)
-
fix:– applicable when the action is fixing a bug. -
feat:– applicable when you add a new feature. -
BREAKING CHANGE:- applicable when you introduce a change that might require certain aspects of the program to be updated or upgraded to avoid disruptions. For example, replacing deprecated resources with new ones might disrupt functionality if there is no backward compatibility. You can also indicate a breaking change by using the symbol '!' right after the type (or scope if available). Example; 'feat(authentication)!:' -
docs:– applicable for documentation.
Others include test: , chore: , refactor: , build: , style: etc. If you are part of a team there might be a convention with customized types that you are expected to adhere to. It is therefore important to get the details beforehand.
2. Scope (optional)
Although providing the scope is optional, it is good practice to include it for clarity. The scope specifies the part of the codebase affected by the changes thus helping readers understand the context of the change. This is especially helpful in large projects with many contributors. It makes collaboration easier.
3. Description (mandatory)
This is the part where you describe what you’ve done. Keep it concise and straight to the point. Make sure that you write it in imperative form. For instance, instead of writing “Added authentication mechanism” you should write “Add authentication mechanism”. This will promote readability in automatically generated changelogs and release notes.
4. Body (optional)
Here is where you can provide more information about what you’ve implemented. Use a blank line to separate the body from the description.
5. Footer (optional)
If there is any metadata you’d like to include do so in the footer. For instance, if the change you’ve made addresses an issue that had been raised earlier you can indicate it here by citing the reference number. Example; 'fix #003'
You can also include reviewer’s name in the footer.
Remember, a scope should be followed by a colon and space before giving the description. You should also keep in mind that BREAKING CHANGE is case-sensitive when included in the footer hence should be written in uppercase.
Examples
- chore(Art_func): change variable “Empty” to “empty”
Change variable name from “Empty” to “empty” for consistency with
the naming convention.
- fix(database)!: modify schema
Modify schema to accommodate only structured data. Dismiss all
other types of data.
- feat: add support for dark mode.
For long messages, use a text editor by running
git commit
without the -m flag. This opens an editor where you can write a detailed commit message. For shorter messages you can just include the -m flag and use the terminal instead of an editor.
git commit -m "subject" -m "body"
Using multiple -m flags helps you format the message correctly by separating the subject, body, and footer.
Conclusion
Writing a commit message should serve the intended purpose. To make it clear and informative, it is recommended that you include at least the type and description of the changes you’ve made. Follow the conventional approach to maintain a good codebase that can support collaboration and automation of various processes. For detailed information be sure to go through the Conventional Commits guidelines.
Top comments (41)
thank you for this info!! i won't write commit messages like
shfkgkdjejeneanymoreAlso, this is what squashing commits was made for (provided you are still on an isolated branch you can force push). Commonly squashed commits for me are:
Yep, well said.
Or updated Readme.md. I hate those commits.
Hehehe
😅
...wait, so
"...in which our hero bravely fixes an off-by-1 error because of arrays that begin with 0 instead of 1" isn't valid? 🤣
If you and your team are consistent in writing commit messages in the style of the Hero Journey, great!
It is valid and better than conventional commits
TBH I don’t like conventional commit messages because in my opinion commit messages should naturally speak about the change not needing a prefix to tell whats is the change itself. Try to automate something (CI/CD) via commit messages for me is a misuse, the message should say what the changeset is doing and not what to do with the changes
What your pipeline will gonna do with “fix: foo bar” change? Test or Deploy the code, does not matter the prefix. Breaking change? Ok the deployment process will stop by “reading” this prefix?
I do believe documentation, knowledge sharing, strong pipeline processes are more effective than conventional commit messages, and also I know this comment is fully of bias 🤣
agreed, relying on commit messaging for some CI/CD function is a misuse, and too risky. They're super hard to enforce anyway, and with standard/conventional commit messages there's still a lot of flexibility.
IMO conventional commits make scanning git history by humans much more effective. Adding any structure to something that differs so much per developer goes a long way. Teams can share scopes, types imply severity (or at least demand different levels of attention), and all of it forces us to easily give context that we often forget about.
My team of 6 uses Commitizen Conventional Changelog in our projects. No complaints so far.
I'd say it often depends of the developer team maturity and size, it could be helpful to enforce standardization.
But totally ok with the second part
The non-conformist in me is yelling "You can't tell me how to write my comment's FU! finger. While the part of me that wants to get a job is somewhat grateful, yet still put off. Future experienced me who knows what pipelines and automation are thinks the other two me's are stupid.
Fix(individualism)!: modify perspective
Modify perspective to magnifying the power of teamwork, inorder achieve gainful employment.
BREAKING CHANGE. Fix #fu-00100
Understood. It's good to find balance as you get more experience to know when to conform and when not to. Great point. Thanks for the post!
I'm afraid your first 2 examples aren't actually written properly, in that the description doesn't really convey what the commit does and one has to go read the body (which requires additional user actions when presented with a list of commits showing only the description, as is frequently the case)
Here are how I would have written them (still following conventional commits, that I dislike for… reasons):
(I'm sure they can be improved, this is only showing how what you put in the body would better fit in the description)
Honestly, I like your opinion a little better than OP's. Thanks for the post.
This is a great format but better for branch descriptions as a branch fix or feature can have many, many commits. One I worked on the other day to add a nice drag and drop feature for files had about 120 commits by the time I was done. Still, the spirit of the format works well for any of the commit messages. Thanks for the post!
Check out this CLI tool to help write your got commits for you!
github.com/di-sukharev/opencommit
Yup, adopting good commit message leads to powerful automation workflow see below:
📜 Better collab flows w. (git) Conventional Commits
adriens for opt-nc ・ Feb 8 '23
Very good point!
Excellent article on the importance of well-crafted Git commit messages! As a developer, it's crucial to maintain an organized and informative commit history to ensure seamless collaboration and make the codebase more navigable.
To further improve your Git workflow, you may want to consider incorporating some tools to simplify the process of writing commit messages. For example, the Leiga IDE plugin can create code commit templates to easily bring issue information into Git commit messages, while also making it easy to update issue status, allowing developers to focus on work in the IDE: Leiga
@allenz_1011 It looks interesting! I just need to know if there is a confidentiality concern with Leiga, considering it will be used with VS Code (code exposure)?"
Fascinating. I'll add this to my extensive list of articles on "how to write a good commit message"
Some comments may only be visible to logged-in visitors. Sign in to view all comments.