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.

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

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 color

I do not understand why people insist on trowing inane technical solutions at social problems. It doesn't work.

I wouldn't say its a lost art... we do this at our company

[0]: https://www.bekk.christmas/post/2019/11/gitmoji-yay-or-nay [1]: https://news.ycombinator.com/item?id=21760021

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

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 emulators

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.

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

I'd posit that well-structured commits are principally for the benefit of the reviewer of the code. Order your commits in a fashion that makes sense narratively, and give them meaningful commit messages. Use interactive rebasing liberally if need be to accomplish this goal.

As a reviewer, you are well within your rights to decline a PR that consists of a single non-meaningful commit message and a +/- 1000 lines diff. Effort is expected from both parties in checking in code.

Two usecases I can think of: non-native English speakers and ADHD developers. For those groups, having some tool that autofills the first draft of the commit message (that you can then modify) would probably improve their overall commit message quality.

A quick google gave me several projects:

- https://github.com/Nutlope/aicommits

- https://github.com/insulineru/ai-commit

I'm sure there's more.

The most important thing to convey in a git commit message is the why, not the what or how.

The title should be a short summary of the change (the what), so that it can easily be searched for.

The description should explain why this change needed to be made. The how and the what can be determined by reading the code. But more often than not, explaining the why helps to clarify intent so that future readers can determine if your rationale still holds.

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

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.

Using a type is to contrived, because your commit will often include e.g documentation and a feature. Splitting them for the sake of following this pattern makes no sense.

On the other hand, job security?

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

I don't think my team would.

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

Yes. And yet:

> - Keep each point brief and focused.

> - Use bullets (-) and avoid lengthy explanations.

No, they lost me there. You often can’t tell the necessary narrative in a single sentence, and you frequently can’t explain why changes were made briefly, and I strongly refute that “avoiding lengthy explanations” should be a goal in commit messages.

I exceed ten lines very frequently, and when working professionally I’ve tended to exceed fifty lines at least twice a year. Coworkers have commented favourably on my commit messages, as unusually useful, and some have even lengthened theirs more often after experiencing them.

I don’t know what my record is, but it was more than 300, though that was as part of a long-lived refactoring branch that I was needing to rebase every week or two for six months as I continued working on it, migrating from an in-house concatenation-and-#ifdef module builder to ECMAScript Modules, and I was maintaining the dozens of commits meticulously, some regenerated automatically and some requiring manual effort, and so I was detailing the semantics of the changes across a large number of files, so it might not count quite so much. But I’ve done over a hundred a few times for other reasons. Keep your mind open, and look at the longest commit messages in popular repositories, and you’ll find there’s a lot of scope for very long commit messages.

—⁂—

I loathe Conventional Commits. It saps the art out of the commit message, the tags are frequently badly applicable, the benefits are negligible to negative (changelogs shouldn’t be generated from commit logs—they should be their own thing), and they’re simply ugly.

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