Skip to content

A guide on commit messages

🦁 Yvonnick FRIN on January 29, 2020

The comic is from Daniel Stori. It is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License The time... [Read Full]
markdown guide

You can share your git commit conventions in the team via e.g.:

add this into your "~/.gitconfig"-file

  template = ~/.gitmessage



Just to confirm - this is a template, but does not act as a linter, correct? So, you could pair this with something like commitlint (


Waouh! Didn't know about it, thank you for sharing!


If you work with Jira, It's also nice to prefix your commit with the ticket number, e.g.

XYZ-123: add the thing

That way you can easily navigate to the corresponding ticket and see why the change was made.


I love linking like this, but it also proves problematic over time as teams move PM software and context is lost. For the most part, I'm trying to get in the habit of writing commits that include the sufficient context to explain why a change was made without relying on a ticket.

... definitely makes for longer commits though /shrug


Maybe put ticket number in the footer of commit message? So it stays linked, but wouldn't clutter up git log since you can't tell at a glance what XYZ-123 means, when viewing git log output.


Checkout a package called commitzen. I've been using it professionally alongside Jira and it's made the commit messages very clean and meaningful.

In addition, utilizing a Changelog and proper versioning is super helpful.


Thank you for sharing about commitzen.

In addition, utilizing a Changelog and proper versioning is super helpful.

I could not agree more!


What a great article!

Usually, I do all my projects on my own, hence my commit habits and good practices are roughly none and this is felt when I work with other colleges in a team, like in a university project...

This article presents itself as an awesome way to start improving these collaboration skills!


Thank you!

Sure, side projects are a good way to practice. I try to pay attention on these details so it helps potential contributors πŸ‘Œ

It is easier to apply on professional work if it is already an habit πŸ‘


Thanks for taking the time writing about this important topic. We also implemented a convention and at the time we were inspired by the following (old) blog post . Combining this with some custom convention for the projects needs is very powerful!

Excerpt from the post:

A properly formed Git commit subject line should always be able to complete the following sentence:

If applied, this commit will your subject line here

For example:

  • If applied, this commit will refactor subsystem X for readability
  • If applied, this commit will update getting started documentation
  • If applied, this commit will remove deprecated methods
  • If applied, this commit will release version 1.0.0
  • If applied, this commit will merge pull request #123 from user/branch

Notice how this doesn’t work for the other non-imperative forms:

  • If applied, this commit will fixed bug with Y
  • If applied, this commit will changing behavior of X
  • If applied, this commit will more fixes for broken stuff
  • If applied, this commit will sweet new API methods

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.


In our project, we combine the conventions for branch naming and commit messages. Then we partially automate the commit message format with git hooks.

For example, our branches are commonly organized by ticket number and type. So, something like bug/#123/moduleA/crash-on-close. You can then setup a git commit hook that provides a template like this:

#123: bugfix: [Fixed ...]


where #123 and bugfix are parsed from the branch name. You can also use git commit templates, but they are not as dynamic as git hooks.


I have come across recommendations to write commit messages in present tense by some people and past tense by some other.

For example,

$git commit -m "Updated the search API to include search filters."
$git commit -m "Update the search API to include search filters."

Any preferences in the tense of the commit message?


Great article!

The only part that I was missing and I would like to understand more on, is once you decide on your project commit message conventions, how do you verify everyone (including yourself) is following it?

BTW, funny story - I actually wrote a really similar post a few months ago:


I really like the depth you decided to go. You had emphasized the value of the message and the explained how it added value to other tools.

I joined specifically to help get this point across.


Thank you for sharing. I definitely added your series in my reading list πŸ™Œ


Great article, thanks! I always have problems with the commit messages. Especially in the new projects. So often it comes to:

rm -rf .git
git init
git commit -am "Initial commit"


Thanks again :)


I wonder if it is safe, if it is ever done, to rename a commit message? --

One more wonder, is, how often should I commit?


It depends if someone or something depend on this commit identifier. Amending a commit and push force it will change the commit identifier.

In my opinion you should commit as often as possible. It will help you split your code πŸ‘Œ Keep in mind you must commit only working things. The first four points in the following article describe well what is a good commit πŸ‘


My commit messages are more like

"Done some stuff"

Cause, not many people really collaborate on my stuff, so I tend to get away on that


If your stuff is open source I would recommend paying attention on your commit history if you want to attract some contributors πŸ˜„


But will you remember why you made those changes in six months time?


No XD! I just accept the repercussions.


This a great article. I am also cleaning up my commit messages for this project SQL practice. I use Visual Studio's GitHub interface.


I think a well structured commit history helps potential contributors. Nice initiative!


I only use GitHub to host my portfolio and maintain my C# page. Contributing to open source is my next step, so I need to write great commit comments


Really nice article! I really love the tips you gave and the convention examples you mentioned.

I think the gitmoji convention must bet a lot of fun to use, although I never used it professionally so far.

thanks for sharing! πŸ‘


Thank you, I use it on professional project. It really depends on your team and the common rules you commit to. In my opinion emojies are compatible with professional project since we already use it a lot in chatting tools at work πŸ˜„


Great article ! Well documented with great sources !


Thanks for Sharing! IΛ‹m looking forward to use your guiding tips in my future projects! ☺️


Husky has something to offer here. It can help automate these things


Sure, automate this kind of checks is nice πŸ‘

code of conduct - report abuse