Commit messages as a thinking and documentation tool
Problem
Users complain that commit messages are often unclear, overly verbose, or generated by AI, making code review and blame difficult; they also lack a clean place for explanatory notes, leading to frustration and a desire for better tooling.
Pain points
- Unclear or overly verbose commit messages
- AI‑generated massive commit messages that are hard to skim
- No clean separation for annotations/context, leading to desire for tools like git‑notes
Questions to verify
- How would a tool that separates explanatory notes from commit messages affect your workflow?
- Would you prefer AI‑generated commit messages to be shorter or to include structured ‘Why/How’ sections?
- Would you use a separate annotation system like git‑notes if it were integrated into your VCS?
Evidence
quote · @Anonymous
Writing is thinking in every situation, not just limited to commit messages. This is a fact that I'm concerned people are forgetting, or worse never understood to begin with.
quote · @Anonymous
Long ago I changed the default commit message to include headers "Why?" and "How?" to remind myself that I need to explain why a change is made (what this article focuses on), and how it is made (different implementation approaches considered). I followed this format for a long time. I was in the top 1% for commit message length at the company.
quote · @Anonymous
I like git-notes (https://git-scm.com/docs/git-notes) for this sort of annotations and context. It's a nice balance - adjacent to commits, follows branch structure, easy to instrument, doesn't muddy the commit history.
Disclaimer: this card is distilled by AI from community discussions as “pain point evidence”. It is a starting point for need analysis and validation, not a “validated market need”. AI has analytical limits; please open the original discussion above to manually verify before key decisions.