How to Write Useful Commit Messages (My Commit Message Template)

Jacob Herrington (he/him) on October 02, 2019

We've all lived the XKCD about git commit messages at some point. I am no exception. This is what the commit messages for my blog look like: f... [Read Full]
markdown guide
 

Nice guide, great points here.

I think commit-messages should be a lot like commenting code. Instead of re-stating the obvious in the commit message, having some meaning definitely gives more value. My general rule of thumb is to write a complete statement, not a question, sentence fragment, or a word. It should have a subject and a predicate in it. That is not to test people's English skills, but to ensure that it provides meaning.

I noticed some repositories have a policy on prefixing with "feat", "fix", "docs", etc. but I'm wondering if anyone finds those useful? To me, those seem like unnecessary clutter and are a crutch for not writing useful commit messages. Is "(feat) Add users" better than "Implement functionality to add users"? I suppose the argument could be they are easier to scan in a listing, but if it is an invitation to be brief then wouldn't that mean having to look deeper into it to really figure out what it is?

 

"I noticed some repositories have a policy on prefixing with "feat", "fix", "docs", etc. but I'm wondering if anyone finds those useful?"

There's an npm package named commitizen that does just the same, it enforces to select the type of modifications that were made and it appends it to the beginning of the commit's subject, I personally find it useful but not strictly necessary

 

As a maintainer, I see the benefit of having some of those prefixes, but I think you can lean on GitHub or GitLab labels for that kind of support.

Good thoughts!

 

There are cases where prefixes like that can be useful - writing "fix" followed by an issue number can automatically resolve said issue on Github, and there are similar integrations with for example JIRA. Granted, it doesn't have to be a prefix, or even be in the subject line for that matter - but still.

Outside of automated stuff like that I suppose it comes down to personal preferences. In my case I have found prefixes like that to be useful sometimes when skimming through a log on projects with multiple people.

 

I like having a Jira (or whatever platform) issue number in it. Even if there is no automation set up to read that, usually the Jira issue title/description/comments give more history of it that might not be captured in the commit message.

 

One team I heard of uses a standardized set of emojis in this same way.

 

That's pretty clever, actually. I've seen people do similar with slack and integrating it with devops.

 
 

Those pefixes can be used for automatic versioning of a library with a tool like semantic-release

 

Great article! What are your thoughts on the Conventional Commits method?

My commits all have a type and a scope plus some info if necessary:

feat(landing): added pricing page

New page for pricing in addition to the section on the homepage
... etc
... etc
 

Should be "add" though, iirc. So I can read your commit like "this commit will add pricing page".
But nevertheless, I'm using this method too and it's great. It looks nice and understandable in the commit log and I can even generate the changelog file without worrying about manual editing of changes.

 

Tagging your commits with the associated ticket I think is the most essential part of a git commit.
I do understand that the author is focusing on just the content. So it's just me saying in addition to.

Depending on your size of the commit you may want to consider how verbose a git commit message should be.

I suppose if you squashing multiple commits to merge into a branch you could then be more verbose. I guess this going to depend on your workflow.

No opposition here, just some thoughts.

 

Absolutely. I'd say 50% of my commit messages are subject line only, you don't always need a commit message with this much context.

I also think tagging a related issue is critical, but of course, that is assuming your issues are kept up to date! 😉

I don't tend to squash commits when I have a choice. I tend to err on the side of too many commits. Atomic commits have always served me well and I would be afraid to lose some of the benefits by squashing too frequently. 🤷‍♀️

 

I used to work for a startup where one of the co-founders insisted you always have a hyphen between the commit message and the id eg.

#243 - This is my commit message

Pull requests would be halted for this superficial format. A simple hook could have enforced that formating to satisfy the co-founder but they also refused to accept an automated solution.

Insanity!

There is enforcing reasonable processes and rituals, and then there is being picky. ;)

 

I usually don't specify the WHY, unless something was rewritten. I usually do:

Additions, changes/fixes and removals

Additions:
 - Added class <Bar>
     - Added new function <foo()> for handling input
 - ... 

Fixes:
- ...

Changes:
- Updated README.md
    - Added todo list
- ... 

Removed:
- ... 
 

I can see how this would be useful, but I think Ben's point about why people look at commit messages is super important.

I don't use git blame to find out what was done nearly as often as why.

 

I love how people in 2019 still repeat the 72 characters limit mantra like they were developing kernel under Linus supervision using terminal from 1984.

 

He said 50 this time.. Our terminals are shrinking. 😱

72 is good for the subject line as a guideline. It shouldn't be enforced in any way. I prefer git clients that just give me a warning when I cross it.

How about the commit body? I've seen some people do manual word wrapping/line breaks there, and some git clients warn when I don't. Any reason to do manual word wrapping?

And markdown syntax in the commit message body, yay or nay?

 

Do whatever works and doesnt get in the way in your team.

Thats my recommendation. ;)

 

I prefer 50 for the subject line specifically because that's when GitHub starts to truncate.

I have my line wrapping done automatically, though.

 
 

I like this kinda commits. I'd add a scope and type like the Angular commit message

Something like

fix(User container): blabla...

Furthermore with this kinda commits you can generate a sweet changelog effortlessly.

 

Nice article, in my company we use the id of the jira task, for example:
"TEST-123: This is my beautiful explanatory commit".
This later shows up in Jira and we know that there is already a commit, PR for a certain task by using the Git plugin for Jira.

 

The last company I worked at did this with Clubhouse (sort of like Jira lite).

 

I really like the template idea. I find quiet often that commit messages are not useful, or they were set the time. But as time went in, they became hard to understand or contain zero context. For which I am also very guilty of writing

 

I'm not always the best at following my own advice here, but having a template goes a long way towards remembering to follow a convention.

 
 

This is in my alias file: alias beams="echo "https://chris.beams.io/posts/git-commit/" | pbcopy"

I followed that to the letter until reading Ben's Twitter thread.

 

What a great series. I feel like if you land on this post you immediately have a great library of resources to read back on if you want to start with the basic tricks and move to this.

 

That's the goal! Series are a great feature for the way I tend to write articles.

 

Carrying a good message , but the template is not practical .
If even we force coders to write such a long commit messages the commit count will drop because they fear to commit, you need to get more familiar with the human nature. No matter what is the standards we do the easiest one

 

Interesting opinion. It doesn't affect me in that way. I also don't write every commit message like this: at least half are subject line only.

 

I dunno. I think the diffs speak for themselves. If I want to know what changed, I look at the diff. Isn't that what everybody does?

ETA: I don't really have time to write pretty commit messages knee deep in feature requests.

 

That's sort of the point of the article. A commit message should be about why not what. What is only useful as an afterthought to support the why.

 

The link to just skip to the template is broken:
//#the-final-template

 
 
 

This is a great read, thanks. You may have finally persuaded me to stop writing my lunch order into commit messages 😇

 

THANK YOU! This has always been a problem area for me. I now know what I should do.

 

There is certainly room for improvement here, but I'm a fan of this model :)

 

Nice easy to adopt and comprehensive template for commit messages.

 

,,My hands are typing words'' will be in my every git commit message from now on. 👌

 
code of conduct - report abuse