My favourite Git commit (2019)
A tiny one-character fix that removed a non‑ASCII whitespace from a config file prompts a wider debate about how much effort developers should put into Git commit messages. Many argue that rich, well-structured messages are invaluable for future debugging, code archaeology, and reviews, especially when issue trackers or wikis disappear or are hard to search; others counter that long, narrative messages are rarely read, belong in separate documentation or PRs, and are undermined by tools that only surface the first line. The thread also touches on related issues such as “smart” Unicode characters breaking tooling, the impact of squash merges and poor history hygiene, and the need for better interfaces that make historical context easier to find and use.
Smart quotes, Unicode, and “gremlin” characters
- Many recount breakages from smart quotes and non‑ASCII whitespace in config or source files (often via Outlook, macOS editors, TextEdit, Notes).
- Some argue typographic quotes and different whitespace must be distinct code points for language and typography; others say over‑semantic Unicode is a design mistake and style should be handled by fonts.
- There’s debate over whether software should auto‑convert smart quotes, with localized quoting rules and language detection making it hard.
- Several users now rely on IDE highlighting, pre‑commit hooks, keyboard remapping, or editor configs to prevent or surface these characters.
Value and style of detailed commit messages
- Many praise the example commit: rich context, clear explanation of a subtle bug, and a record of the debugging process.
- Others find it excessive “wall of text”; they want a concise summary (especially first line), ideally BLUF/TL;DR style, with optional detail below.
- Common suggested structure: short subject explaining problem and scope, then paragraphs on current behavior, cause, and new behavior.
Commit messages vs other documentation
- One camp sees commit messages as key, durable documentation—especially when doing
blame/history spelunking years later or when systems like Jira/Confluence disappear. - Another camp prefers to keep deep design rationale in issues, PR descriptions, or markdown docs, since commit messages are immutable and harder to refine collaboratively.
- Broad agreement that commit messages should document “why” more than “what”; the diff already shows the code changes.
Tooling, workflows, and discoverability
- Several note that common tools and hosted forges surface only the first line, so long bodies are underused.
- Some argue Git and GUIs make history exploration too tedious, discouraging reliance on commit messages; others reply that good editor/CLI tools (blame, log, magit, IDE integrations) make it quite usable.
- Squash‑merging and long‑lived, messy branches are criticized for destroying useful history and encouraging “checkpoint” commits.
- There’s frustration with poor error messages and weak validation for invalid encodings; better tooling could have prevented the bug entirely.
Practical tips mentioned
- Use editor configs, syntax highlighting, or hooks to flag non‑ASCII whitespace.
- Prefer atomic, well‑scoped commits with meaningful messages; treat commit messages as “notes to future you.”
- Avoid relying solely on external trackers or PRs; link them, but keep essential context near the code or in the history.