Subject-First Commit Messages
Debate over “subject-first” versus traditional verb-first commit messages highlights how differently teams use version control history. Some engineers scan logs and want concise subjects that foreground the affected component or behavior, while others rarely revisit commits and see strict formats as low-ROI bikeshedding compared to diffs, PRs, and issue trackers. The exchange surfaces deeper questions about whether commit messages should primarily serve humans or tooling, how much “why” belongs in Git versus ticket systems, and how workflow choices (e.g., squash merges, pairing, no PRs) shape what a “good” commit message even means.
How often commit history is used
- Experiences diverge sharply. Some say they almost never read old commit messages in years of work; others report using history or blame weekly or even daily.
- Common uses: debugging (“why is this code like this?”), tracing when behavior changed, bisecting for regressions, and understanding impact on particular lines/files.
- Several argue messages rarely add more than the diff and are often low quality (“wip”, “update”), which discourages relying on them.
What good commit messages should contain
- Many want commit messages to capture “why” and high‑level “what,” letting the diff provide detailed “how.”
- Short, scannable subject plus optional detailed body is a widely liked pattern.
- Some see commit messages as mostly for their own intermediate work; others as long‑term shared documentation and changelog source.
- Consistency across the team is often viewed as more important than any particular style.
Subject‑first vs verb‑first styles
- Pro subject‑first: putting the most variable/important part (affected subject/component) first supposedly improves scanning, similar to list design and eye‑tracking insights.
- Critics dispute both the readability and the claimed psychological backing, arguing verbs/actions are what matter (“what changed”) and that the examples are too vague.
- Some prefer component‑prefix formats or conventional commits (
type(scope): summary), which categorize changes and support tooling.
Commit messages vs tickets and other artifacts
- Many emphasize including ticket IDs to link to richer business and discussion context; others dislike IDs in titles, preferring them in bodies or trailers.
- Several warn that ticket systems and URLs change or disappear, making commit‑only IDs or links brittle; they advocate self‑contained commit explanations.
- One team describes a broader method: no pull requests, heavy pairing/mobbing, text‑file work and equipment logs in git, and commit messages primarily as concise, subject‑first indices.
Meta: value and bikeshedding
- Some see commit‑style debates as low‑ROI bikeshedding compared to product issues.
- Others argue that poor messages cause significant long‑term time loss and that modest discipline here pays off.