How to write good Git commit messages

Your argument that "most engineers don't care about commit messages, so they must not be important" is akin to "most people are overweight, so health is unimportant".

So, status quo rules, right?

But as your predicted person who nearly always writes this style of messages and who frequently dives into old commit messages, PRs, and tickets: this shit is not hard. It does not consume much time. It is not a deep skill, it's a basic skill, almost at the level of correct indentation in terms of effort required.

It just takes a second or two to think of what your commit does and maybe why you didn't do it the other way, then drop in a ticket reference. A tool can even do that last part! As a bonus, there are times when I tried to explain why I did something and then thought of a better way or a bug I'd missed.

If everybody did this basic exercise that takes just a minute, the commit history might actually be useful. Then most people might use it, who knows!

I think what matters is the type of project. A lot of commercial software is all about moving fast and not caring too much about the past. In such a setup, writing good commit messages may be less useful or even seen as a waste.

For software built to last however, I think good commit messages are invaluable. Issue trackers are replaced, documentation is rewritten or lost, comments are modified; but commit messages stay the way they are. This helps you get a better understanding of why decisions were made, something rarely documented properly.

Last sensitive code I touched is a trading platform that must be responsible for a few billions of dollars a day (could be a trillion, not sure, didn't finish adding logging). It was initially created in 2006, followed by a few commits over the couple next years, then basically untouched for the last decade or so.

Just from the first 10 commits message and the author's name. I can tell you this was hacked-in grossly over a few weeks, because everything that guy did was hacked in quickly and filled with security vulnerabilities (he worked under very limited time constraints). Yet the software does the few things it was meant to do very well, so much so that it lasted this long mostly untouched and was built upon. The history shows the critical core code has less than one patch a year, mostly fixing trivial matters like a new path or syntax change from the language. I bet the project will be moderately easy to patch and upgrade because work from that guy at that time is usually decently organized and limited in scope to the essentials.

Lesson is. If you work in a long term industry (aerospace, defense, finance, healthcare) and long term projects, it's very likely that the product will still be running a decade from now and it is expected that future developers will be reading the history of commits.

Also, pointing to a JIRA issue, etc. if your company uses that is a nice way to complete the loop, the one link that explicitly ties code to planning.

> I'm sure someone will say "but I use the history ALL THE TIME to source dive and paragraphs of context are super helpful". This is not the case for 95% of developers or projects so I can't really endorse spending time learning this "best practice".

> It's fine to be aspirational, but it's such a shame if people see posts like this and think they are failures or "bad" developers or that this is a widespread practice.

I'm that person who's often digging into the history.

It's often to understand other things that the people writing poor messages were sloppy about.

So sure, focus more on writing good code than writing good messages but the truth is that the context of the code and the feature will change over time so preserving the original context you had in your head when you wrote it is super valuable when the next poor sap has to come along a year later and change it.

I mostly work on relatively short term projects these days rather than long lived products and so my commit messages tend to be single sentences, with an extra paragraph if it was particularly involved. It takes little time and once in a while will be useful.

I probably lean more towards them not mattering that much relative to what anyone who talks about "best practice" would like to see. That said, I picked up a codebase from another team the other day where one commit message was simply a ";)" and the rest not much more in depth. That did make me wince a bit.

You're right that 99% of the time they will never get looked at again. And that's fine, but when deciding how much time to spend on your PR they're very helpful.

There are a lot of things in software that need to be possible, but you don't need (or want) the entire team doing it all the time. A team made entirely of 'people like me' would be a disaster. But a team without anyone like me will die a slow and lingering death and not even know why.

It's important when thinking of group behavior - be it work or personal - to differentiate between "I don't need this." and "nobody should have this."

The only method that consistently results in atomic commits is to squash commits when merging, in which case the commit message is your PR title/contents. The nice side effect is that these messages should absolutely be readable since your audience was your code reviewers.

Perhaps the solution is to train developers to look at commit messages then? Source control is amazingly powerful and nearly universally used at this point. Why not make the most of this?

Myself I use vim and the vim-fugitive plugin. Being able to do ":Gblame" is amazing. And then being able to step back in time to see what the code looked like before this commit is great too.

edit: Another blog has a simple reason https://chris.beams.io/posts/git-commit/

> 4. Do not end the subject line with a period

> Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to 50 chars or less.

So I think there's a tooling reason for squashing - more effective use of `git bisect`.