The Lost Art of Commit Messages
60 comments
·March 25, 2025saagarjha
tux3
The author is working in an environment where, left to their own device and allowed free form messages, programmers write the three word sentences shown in the blog post.
This is the downside of the variation in style across contributors. It works if people want to build something, and not just do the minimum. Open source projects frequently have no such limitations.
But I am sad to report that some people appear to need the structure.
saagarjha
Address structural issue with code contributions
In some cases, it's possible to end up with commit messages that carry
very little value. Unfortunately, while the minimum is clearly
insufficient, it is possible to "expand" the minimum into a specific
format without substantially improving the quality of the commit
message. For example, a substantial refactor can easily just be
described as a list of the changes that it included, rather than a
rationale for why it was done (which is not readily apparent from the
change itself).
In the long run, problems involving people can be improved by process,
but cannot wholly be solved by them. Pernicious failures need to be
acted upon directly. Demonstrating the value of good commit messages is
often a better driver of improvements than a template that is a chore
to fill out.MrJohz
In my experience, people write overly short commit messages when they're writing too many commit messages. The solution is usually not to teach people to write better commit messages (although that's also good), but to teach them how to group and bundle commits together to create a meaningful standalone patch.
One of the easiest ways to start there is to adopt PR-based review systems, where any number of commits can get pushed to a git repository and then reviewed as a single block. This is fairly inflexible, but it is very simple to get started with (no need to learn any special rebasing commands, just add, commit, add, commit, push). Most git forges allow you to do squash merges, so everything in the PR will become a single commit, usually with the PR description as a commit message. Then you can refine the commit and commit message during the review process.
There are better tools out there, but in my experience, this is the quickest way to get started for most teams, especially as you're probably already using a forge that allows you to do all of this already.
chrismorgan
Also, reconsider column-based hard-wrapping entirely,
and consider wrapping mostly on punctuation,
or other reasonable opportunities when it gets a bit long
and you don’t really want to insert punctuation.
This is not without its drawbacks and limitations—
most software when rewrapping won’t cope with trailing em dashes,
and you’ll end up with extraneous spaces when the lines are merged,
even though this is *always* how wrapping has worked around dashes.
Over time, this will definitely influence your writing style.
Your sense of æsthetics will push you to reword sentences,
because otherwise the edge is too ragged for your liking,
and at some point you’ll see a pattern in a paragraph,
and feel an uncontrollable urge to continue it,
and you’ll waste a bunch of time tweaking,
and maybe no one will appreciate it.
But you’ll appreciate it.
It’ll be fun.
Mostly.
But seriously, you *will* become more aware of things like clause length,
and your writing will probably improve.
And after writing verbosely for a long time,
you’ll focus on concision,
and that’ll be another challenge.
And it’ll be fun too.
Mostly.
Then probably someone will take over your pet docs project,
and mandate an autoformatter that rewraps it to 59 columns.
Stubbornly, in the quiet of your mind, you’ll make it work.
It’s a greater challenge, but you won’t lack determination.
Style guides come, and style guides go; when this one goes,
your lines can remain the same, needing no fixing, perfect.
—⁂—
And really, just look at how the last paragraph of the parent comment looks,
before and after:
Finally, commit comments definitely should have jokes in them. This is
actually more critical than wrapping them at 72 characters.
—⁂—
Finally, commit comments definitely should have jokes in them.
This is actually more critical than wrapping them at 72 characters.
Much more beautiful, is it not?benji-york
You might like top's commit messages, e.g., https://gitlab.com/procps-ng/procps/-/commit/e6f22569e9db16d...
commit e6f22569e9db16dbef7d9bdee5bb41b8cb7a03ca
Author: Jim Warner <james.warner@comcast.net>
Date: Tue Jul 23 00:00:00 2024 -0500
top: attempt once again to allow help text translation
Back when our release 4.0.1 was being readied, sources
were sent to the TP (Translation Project). However one
person named Benno Schulenberg refused to release them
for translation. His stated reason was the top command
line help text which then finally included long forms.
He demanded that the help text be broken into separate
strings instead of a single large string. But, all the
top text (some much more complex) has just one string.
So that stated reason was, at the least, inconsistent.
[ I suspect the real reason was that Mr. Schulenberg ]
[ thought that the carefully right-justified English ]
[ wording would also be required of translations too ]
The bottom line was that Benno took it upon himself to
change the TP motto from "you code, we translate" into
"first we tell you how to code and then we translate".
Rather than bend a knee to that despot, I disabled the
text entirely, admittedly denying users a translation.
Now, with this commit we enable translatable help text
but with a hint included to ignore the justified text.
Reference)s):
. Oct, 2022 - finalized translation exclusion
commit ab05a3785f29cc4b754e17c53bfb3d8ba054563e
Signed-off-by: Jim Warner <james.warner@comcast.net>darknavi
> Having commits prefixed by "chore:" or "docs(ui):" aren't that useful.
I don't use those for humans, I use those for tooling, such as semantic-release. The human-readable bits come after that.
sam_lowry_
I always thought we have tags for tooling.
windward
And the rest of the message. And git-notes.
Reducing the human-readability of the most human-presented part of the commit, to make it easier for the can-do-billions-of-operations-a-second machine, seems backwards.
Hojojo
I quite like my current system.
One word naming the topic or area or system that was changed, then colon separated with a very short sentence giving a summary of the changes, then two lines later (if necessary), a bullet point list of the most important/noteworthy changes, then an explanation for why a thing was changed (if any change in the commit warrants it).
Honestly, I know most people won't go beyond the first line, but I do find the rest of it very helpful for my own work if I have to go through the commits sometime in the future.
It also helps that most of it is optional and I decide on a case by case basis whether just the first line is sufficient or I need the whole thing.
I see in the comments people questioning the purpose of a bullet point list, but it actually is helpful. I don't want to have to check the diff for every single commit if I don't have to. It's time consuming. If a commit message can tell me immediately if it touched something I'm interested in, that's a big time and effort and mental bandwidth saver.
Example:
auth: Refactored and fixed edge cases
- Fixed incorrect handling of token groups
- Added role enum to replace static strings
drac89
Looks beautiful. And the best part is, if you ever need to fill out a PR template with what you did or list the changes, it becomes so much easier. You don’t even have to remember exactly what was changed, it’s all right there in the commit message.
BrandoElFollito
I found that for my home-grade development the commit messages generated by copilot are very good.
rejschaap
You get some of this for free if you create branches and squash merge them when finished. Without needing to think much about commit message, just a few words per commit is enough. This is good enough for me and I don't need to waste any time thinking about it.
Example commits of something I worked on a few days back:
$ git l feature/character-selection
c54825f 3 days ago Robert Schaap (feature/character-selection) Simplify color picker, fetch current color
d512569 3 days ago Robert Schaap Fix recolor for female, clean up files
6d05ce4 3 days ago Robert Schaap Add color picker to change shirt color
441180b 3 days ago Robert Schaap Show male in editor
17045dc 3 days ago Robert Schaap Remove old character
95772ff 3 days ago Robert Schaap Add characters
$ git show HEAD~1
commit be50e0d701d565cebdf4f29e0c9d8030a1a8faf7
Author: Robert Schaap
Date: Mon Mar 24 21:29:20 2025 +0100
Character selection (#14)
* Add characters
* Remove old character
* Show male in editor
* Add color picker to change shirt color
* Fix recolor for female, clean up files
* Simplify color picker, fetch current colorkqr
Granted, I'm not the target audience of your commit messages, but they tell me very little about what happens.
> Add characters
I can probably tell from the code that that's what's happening. But what requirements drove these particular characters?
> Remove old character
What makes it old? How would I recognise an old character in the future?
> Show male in editor
Why did male not show before? Was there a bug or a partially implemented feature?
> Fix recolor for female, clean up files
What does it mean to "fix recolor"? And even worse, what is "clean up files"? What requirements drove this file cleaning? Why were the files unclean in the first place?
etc. Commit messages in the style of "fix X" or "add Y" or "remove Z" or "nondescript action on W" are the bane of my existence. They seem so meaningful but they don't tell me anything when I'm trying to trace why a particular bug was introduced – or whether it's even a bug in the first place.
Cthulhu_
Yeah I think the most important thing to think about when writing a commit message is the intent; a LOT of people use it as a "work log", describing what they did like "removing a character" or "add color picker".
But a commit message needs to describe what the commit does, when applied. A good rule of thumb - also explained on the git site [0] - is to put it in a template like "When applied, this patch will <your commit message>".
The grandparent comment is almost there though, using the right tense of "fix" instead of "fixed", the latter being in the work log form of "I fixed such and such".
[0] https://git-scm.com/docs/SubmittingPatches/2.2.3#:~:text=Des...
ahofmann
Yes! Please tell me _why_ the commit happened. The _what_ is in the diff, so almost no need to tell me in the commit message. Often I get commits with some LLM-generated slop in the commit message. It always looks good and always tells nothing. Commit messages like that are garbage.
nloomans
These example commits seem like pretty bad commit messages to me. They are just a summery of the changes (something a motivated reader can rediscover by reading the diff), while leaving out the why, which will be lost to history if not documented.
retSava
Yes, the why is very very important, but imo it's also useful with a one-liner summary of the actual change.
Consider a trivial change but affecting tens of places in the code, eg an API change. It's very useful to be able to quickly glance past "use new abc-API; required since dependency X bumped to Y" and mentally move on, rather than actually having eyes scanning over those actual changes.
gherkinnn
A dev culture that produces nothing but wip and fix bug commits (frequently adding unrelated refactors) will continue to produce noise but prefixed with chore(code): fix bug. I fail to see the benefit behind this and conventional commits.
I do not understand why people insist on trowing inane technical solutions at social problems. It doesn't work.
addisonbeck
`chore(code): fix bug` doesn't follow conventional commits, so it's not at great example for this point.
In my experience conventional commits tend to lower character counts and improve the readability of messages. `bug(auth): adjust XYZ` is shorter than `fix auth bug by adjusting XYZ`.
matsemann
What about Gitmoji? [0] Didn't get much love when discussed here[1] but fun concept. At least it makes you think about the commit message, which is better than not. And each commit having one selected emoji forces you to make one commit per improvement, so you can't bundle stuff together.
[0]: https://www.bekk.christmas/post/2019/11/gitmoji-yay-or-nay [1]: https://news.ycombinator.com/item?id=21760021
agnishom
Similar to https://www.conventionalcommits.org/en/v1.0.0/ right?
I wouldn't say its a lost art... we do this at our company
rollcat
Depends. Sometimes a one-liner or a reference to a ticket is enough.
There are times when I make a one-line change and write a paragraph or two explaining why it had to be done. But these kinds of things often drown in the noise of a dozen other changes. If that one was important enough, I will reference it in an ongoing discussion or documentation, or at least include "read below:" on the first line.
I usually see people include a more elaborate commentary with the pull request. If the changeset is good but the series of individual commits is a bit messy, just merge by squashing.
(Also: this comment is meta.)
Cthulhu_
A one-liner: sure. A ticket? No; ticket systems are transient and not always available. You shouldn't need to open an external system that may no longer exist in 20 years time (for example) to get the full context.
Compare the Linux commit history, every commit has its full context and explanation and they do not rely on external systems.
yaris
Our ticket system survived almost 20 years and is useless anyway, because approximately half of the history consists of pairs like: commit 12345 ”fixed a bug, see ticket 54321” - ticket 54321 ”fixed by commit 12345”.
dirkf
20? Try 5...
I"m working on a repository that uses at least four different jira ticket number formats. All commits should have a jira reference but I think only the current format can still be looked up. And maybe the predecessor if you know what jira field to query. All the rest are lost in corporate limbo. Not that those tickets added much more context to the actual commit...
So yeah, always write your commit messages as standalone as possible.
drac89
I agree maybe not adding the ticket link is better if you know that the system might not be available in the future.
You can not avoid it all the time but maybe It's better to use the PR description for that purpose.
null
pydry
If I feel the need to write a paragraph in a commit message it's usually a sign that Im writing prose that belongs in actual docs.
Commit messages are a great place to bury docs nobody will look at.
HelloNurse
The quality of commit messages depends on context. The author seems focused on bringing order to long freestyle messages, presumably for the purpose of accreting a rich but readable history log in long-lived branches, but not all commit messages are like that.
For example, when typical commits are about solving or implementing some support ticket, issue, new feature etc. that is documented elsewhere correct references are far more important than classification of the commit type or descriptive details; special commits (refactoring, chore, docs etc.) are easily noticeable because they don't reference a specific issue and many details are better omitted for the sake of deduplication.
fix(ui): correct alignment on dashboard widgets
- adjust CSS flex properties
- test on multiple screen sizes
Fixes #204
#204 - adjusted CSS flex properties of dashboard widgets; tested on multiple screen sizes
#204 - same CSS flex properties for all dashboard widget DIV elements; tested on 800*600, 1880*960 and 2900\*1600 browser windows but not on the standard smartphone emulatorsRustyRussell
I don't care, as long as a commit which fixes a crash, compiler error or test failure quotes the errorv. This helps searching for issues, and also helps later if you find they mis-diagnosed the problem.
Other peeve: quote the core of the bug report you're closing, so when GitHub inevitably goes away/turns evil/starts charging, you don't lose half your knowledge. The git tree should always stand alone.
stared
I second the Angular-style git commit message convention (https://github.com/angular/angular/blob/main/contributing-do...). Though, it is also art that I have lost.
On a lighter note, I recommend "8 Types of Commit Messages That Show He's NOT the Man for You" https://web.archive.org/web/20210606005031/https://www.codem...