✳flâneur — a map of the web's best reading

Writing commit messages

chiark.greenend.org.uk · 10,151 words · saved by 1 readers

Of course, there are lots of guides to commit messages already. Why am I bothering to write another one? Mostly because, when I’ve looked at other guides, they don’t seem to be focusing on the most important things. The one that first started me making notes towards this article consisted of a 7-point list of guidelines, most of which were tiny details of the initial ‘subject line’ part of the commit – what tense to use, whether to end it with a full stop, capitalisation – and the final rule just said ‘Use the body to explain what and why vs. how’. To my way of thinking, that’s focusing on the trivial and neglecting the important. Yes, it’s nice to have a consistent grammatical style in your subject lines – but it’s not vital. Not the same way that ‘include all the important facts and reasoning’ is vital. A commit-message guide ought to focus on information, not typography. What do you put in, and what do you leave out? The rule that said ‘explain why and what’ should have been most of

Writing commit messages Writing commit messages [Simon Tatham, 2024-05-19] Introduction Why write yet another of these guides? What’s your authority to pontificate on this subject? What information should I include? Who will read my commit message, and why? What will someone get out of reading the commit message? OK, so what information should I include? In the commit message, or somewhere else? Use commit messages in preference to cover letters Commit message describes changes; code comment describes how things are Consider adjusting the patch to make the commit message simpler Writing style

Explore this link on the map →

saved by

related reading