DEV Community

Cover image for Are You Writing Your Git Commit Messages Properly?
Rabin Otieno
Rabin Otieno

Posted on

Are You Writing Your Git Commit Messages Properly?

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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 (40)

Collapse
 
qwertyy profile image
qwertyy

thank you for this info!! i won't write commit messages like shfkgkdjejene anymore

Collapse
 
jhulten profile image
Jeffrey Hulten

Also, 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:

  • take 1
  • take 2
  • take 37
  • ffffffffuuuuuuuu
  • am I dyslexic?
  • I hate everything
  • I AM A GOD!
Collapse
 
documendous profile image
Documendous

Yep, well said.

Collapse
 
melroy89 profile image
Melroy van den Berg

Or updated Readme.md. I hate those commits.

Collapse
 
martinbaun profile image
Martin Baun

Hehehe

Collapse
 
allwelldotdev profile image
Allwell

😅

Collapse
 
linkbenjamin profile image
Ben Link

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

Collapse
 
jhulten profile image
Jeffrey Hulten

If you and your team are consistent in writing commit messages in the style of the Hero Journey, great!

Collapse
 
katafrakt profile image
Paweł Świątkowski

It is valid and better than conventional commits

Collapse
 
alxwnth profile image
Alex

I’m adopting this!

Collapse
 
akindejihill profile image
Akindejihill

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.

Collapse
 
graphei profile image
GRAPHEI

Fix(individualism)!: modify perspective

Modify perspective to magnifying the power of teamwork, inorder achieve gainful employment.

BREAKING CHANGE. Fix #fu-00100

Collapse
 
documendous profile image
Documendous

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!

Collapse
 
habutre profile image
Rogério Ramos • Edited

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 🤣

Collapse
 
ademagic profile image
Miko

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.

Collapse
 
mevrin profile image
Matthieu Evrin • Edited

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

Collapse
 
tbroyer profile image
Thomas Broyer

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):

chore(Art_func): consistently use "empty" variable name casing
Enter fullscreen mode Exit fullscreen mode
fix(database)!: accommodate only structured data

Dismiss all other types of data.
Enter fullscreen mode Exit fullscreen mode

(I'm sure they can be improved, this is only showing how what you put in the body would better fit in the description)

Collapse
 
documendous profile image
Documendous

Honestly, I like your opinion a little better than OP's. Thanks for the post.

Collapse
 
documendous profile image
Documendous

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!

Collapse
 
drewpayment profile image
Drew Payment

Check out this CLI tool to help write your got commits for you!

github.com/di-sukharev/opencommit

Collapse
 
adriens profile image
adriens
Collapse
 
documendous profile image
Documendous

Very good point!

Collapse
 
allenz_1011 profile image
allen_z • Edited

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

Image description

Collapse
 
chandrashekhar profile image
Chandrashekhar Mehta

thanks for explaining this messages in detail, I didn't know it before.

Collapse
 
emelie profile image
Chukwuemelie Obiora

Thanks for sharing

Collapse
 
michlutkhebee profile image
Michael lutta

Asante bwana otieno. I've actually learned something new today🙏

Collapse
 
jmccabe profile image
John McCabe

Fascinating. I'll add this to my extensive list of articles on "how to write a good commit message"

Collapse
 
ppaanngggg profile image
ppaanngggg

thanks for sharing, there are some tools can help writing commit messages

Collapse
 
jhulten profile image
Jeffrey Hulten

I use commitizen to both provide a pre-commit hook and automate the questions to build a message.

github.com/commitizen-tools/commit...

Collapse
 
zakari714 profile image
Zakari Adamu

Awesome. This was really a game changer to committing properly now.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.