DEV Community

loading...
Cover image for How to Write Useful Commit Messages (My Commit Message Template)

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...
pic
Editor guide
Collapse
ryansmith profile image
Ryan Smith

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?

Collapse
mohamedelidrissi_98 profile image
Mohamed ELIDRISSI

"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

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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!

Collapse
svsven profile image
Sven van Steenis

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.

Collapse
ryansmith profile image
Ryan Smith

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.

Collapse
codemouse92 profile image
Jason C. McDonald

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

Collapse
emptyother profile image
emptyother

How would that work? Replace ✔ for "fixed", 🆕 for "feat", 📄 for "docs" in the commit messages or something?

Thread Thread
codemouse92 profile image
Collapse
blacksonic profile image
Gábor Soós

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

Collapse
andrewbrown profile image
Andrew Brown 🇨🇦

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.

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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. 🤷‍♀️

Collapse
andrewbrown profile image
Andrew Brown 🇨🇦

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!

Thread Thread
jacobherrington profile image
Jacob Herrington (he/him) Author

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

Collapse
dinkydani21 profile image
Danielle

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
Collapse
defman profile image
Sergey Kislyakov 🇷🇺🇺🇸

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.

Collapse
benstigsen profile image
Benjamin Stigsen

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:
- ... 
Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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.

Collapse
raulingg profile image
Raul Robinson Quispe Mendez

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.

Collapse
nbull92 profile image
NBull92

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

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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.

Collapse
pavelloz profile image
Paweł Kowalski

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.

Collapse
emptyother profile image
emptyother

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?

Collapse
pavelloz profile image
Paweł Kowalski

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

Thats my recommendation. ;)

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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

I have my line wrapping done automatically, though.

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

Obviously, it's preference, I like it though.

Collapse
vbarzana profile image
Victor A. Barzana

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.

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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

Collapse
alialp profile image
Ali Alp

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

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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.

Collapse
andrewsmith289 profile image
Andrew Smith

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.

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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.

Collapse
ben profile image
Ben Halpern

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.

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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

Collapse
patallen profile image
Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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.

Collapse
hasii2011 profile image
Humberto A Sanchez II

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

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

Hmm! That might be a bug with DEV, I'll look into it :) Thanks for letting me know!

Collapse
hasii2011 profile image
Collapse
adam_cyclones profile image
Adam Crockett

"Aaaaaaa 🥰" perfection.

Collapse
walalm profile image
Waldy Almonte

Nice easy to adopt and comprehensive template for commit messages.

Collapse
granttransition profile image
Grant Smith

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

Collapse
kristijanfistrek profile image
KristijanFištrek

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

Collapse
codemouse92 profile image
Jason C. McDonald

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

Collapse
jacobherrington profile image
Jacob Herrington (he/him) Author

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

Collapse
drozerah profile image
Drozerah

Here is the commit message style guide I Am using => udacity.github.io/git-styleguide/

Collapse
ranggakd profile image
Retiago Drago

Hello, I'm a newbie around here. But I want to know your opinion about these kinds of commits in here
:))