The Lost Art of Commit Messages

saagarjha · 2025-03-25T08:24:01 1742891041

  Reject commit message suggestions
  
  When working on large software projects, commit messages that follow
  the format suggested by the author rarely provide additional value.
  Having commits prefixed by "chore:" or "docs(ui):" aren't that useful.
  Instead, some of those 50 characters can be used for more descriptive
  titles. Commit messages are often the best and only context available
  when bisecting a bug, so bullet points only really make sense when
  making a list. Prose works just fine.
  
  Writing styles vary across contributors but it's much more useful to
  get *anything* from someone in their preferred format than nothing at
  all because they are frustrated with rules. Some committers do have a
  special "committer voice" that they use when describing complex changes
  in a commit message. For example, the text here is slightly abridged
  and focuses less on the first person than what is typically expected.
  This evolves naturally from writing these.
  
  Finally, commit comments definitely should have jokes in them. This is
  actually more critical than wrapping them at 72 characters.

nindalf · 2025-03-25T08:28:26 1742891306

This isn't prose, it's poetry.

rejschaap · 2025-03-25T08:14:53 1742890493

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

Then when I squash merged it I ended up with this commit message:

  $ 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 color

kqr · 2025-03-25T08:22:40 1742890960

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.

nloomans · 2025-03-25T08:24:48 1742891088

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.

rollcat · 2025-03-25T08:21:15 1742890875

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.)

vim-guru · 2025-03-25T08:27:08 1742891228

I prefer:

damnitbuilds · 2025-03-25T08:27:42 1742891262

Do people really gain as much time from being able to read these long messages as they lose in writing them?

I don't think my team would.

Did the author measure this ? If not, he's the monkey.

Phenix88be · 2025-03-25T08:24:10 1742891050

I rarely read the commit messages. It's often faster to just read the code than an obscure description, I'd rather have a small sentence that summarizes what the diff is doing than a technical paper explaining every change in the commit. I don't read pass the title.

IshKebab · 2025-03-25T08:28:34 1742891314

Most of the time that's fine, but then you'll find a bit of code that's broken and the change that added it makes no sense and the commit message is empty. Kind of infuriating.

fiskfiskfisk · 2025-03-25T08:16:26 1742890586

And please include the why.

From the article: "- adjust timeout settings to prevent crashes". Include the details of why the timeout setting lead to crashes; what were the inputs and the cases that caused this.

This lets us decide whether the fix stays or goes the next time there is an issue in the same piece of code, or your commit broke something unrelated - the person fixing it needs to know _why_ you changed the code.

lima · 2025-03-25T08:17:56 1742890676

One of the best things about Gerrit - besides stacking and turn-by-turn review - is how it emphasizes good commit messages by making them part of the process.

Each commit becomes one "unit of review", and the commit message can be reviewed just like the code changes.

ziofill · 2025-03-25T08:22:22 1742890942

Wow, thanks for this page, I can almost take it as-is and create a Cursor rule for writing commit messages ^^’

Cthulhu_ · 2025-03-25T08:23:23 1742891003

nit: the author proposes "short descriptions" like "fix null pointer exception in payment module" and "refactor data processing pipeline", however "fix" and "refactor" are already in the "type" part of the commit message. Possibly, "payment module" and "data processing pipeline" can (should?) be extracted from the "scope" element. The characters left over after the type and scope can be used smarter.

agnishom · 2025-03-25T08:07:11 1742890031

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

tobyhinloopen · 2025-03-25T08:17:38 1742890658

--message "wip"

Why do we care about commit messages? I only read them when rebasing.

naavis · 2025-03-25T08:26:14 1742891174

They are incredibly helpful when you are trying to find where a bug was introduced, and trying to figure out why some piece of code is the way it is.

charcircuit · 2025-03-25T08:14:25 1742890465

>while pushing changes that could rival a novel in length

How is distilling a novel down to a short description and 2 points any better? This format is too limiting.

（评论） (comments)

（评论）
(comments)