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
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.
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.
