Chris Beams, a software developer, wrote a widely cited guide to writing good Git commit messages.
HN commenters repeatedly cite it as their favorite reference on commit message style, pointing to its seven rules and its advice on explaining why rather than how.
This repo's commit messages are not good:
"A few more minor tweaks."
"A few more minor changes."
"Some extra file-list safety checks."
https://github.com/WayneD/rsync/commits/master
Those are the full commit messages. By way of comparison, here's what commit messages to git itself look like:
https://github.com/git/git/commit/198551ca54f6ff1c95c9357ccca9ae37298811bf
https://github.com/git/git/commit/dee8a1455c8ad443ef59e0d5b7c168886e50b9ea
Each commit contains paragraphs of explanatory material. Jeff King's commit messages are "gold standards" to me, often well exceeding the size of the diff itself:
https://github.com/git/git/commit/aa0834a04e1d9d3ab81ecd4a4a138233e6e234ed
https://github.com/git/git/commit/38f865c27d1f2560afb48efd2b7b105c1278c4b5
https://github.com/git/git/search?q=author%3Apeff&type=commits
Please folks, I beg of you, spend time writing your commit messages. You're not writing them for you today. You're writing them for others, including your future self. They should explain the commit: What is its goal? Why does it exist? Why was it written in this way? What other context does the developer need to understand this commit?
A PR description is not a substitute for a good commit message for multiple reasons:
1. If the PR is a single commit, then it's just the commit message and your job is probably done.
2. If there are multiple commits, then the PR description should summarize the goal of the aggregate of its commits.
3. The PR description is…
In my opinion, commit messages should say "what" changed, if necessary "why," and usually not "how."
This person has a similar guideline:
https://cbea.ms/git-commit/#why-not-how
- "Why" can sometimes be inferred easily from "what," e.g. for some simple bug fixes, but sometimes not, so that's a judgement call. (I don't think I'm disagreeing with the website here; I'm just saying that sometimes "why" doesn't need explicit language.)
- To answer "how," directly reading the code or the code diff is usually the best way.
- "What" can also be answered by reading the code diff, but providing a high-level summary in the commit message can save future maintainers a lot of time.
> Never say what you ware doing (it's obvious this commit is updating build scripts)
DEFINITELY say what you are doing. And then say why.
This blog post is a good description of the most prevalent convention in how to write good and useful messages (e.g. this is what the Linux Kernel does and given the history of git there's some flow down): https://cbea.ms/git-commit/
The key thing that means you should start with what is having a short one-line summary of what you're doing so you can look at a simple log and see which commit you're interested in.
This is just polishing bad commit messages, it doesn't make them better.
A commit message should tell you why the code changed, not summarize what changed. I can read a code change and see what it does, but I can only guess what caused that change to be made unless the message tells me what was in your head (unless it's a trivial commit like a typo fix)
See eg https://cbea.ms/git-commit/#why-not-how for a longer discussion.
It's great to see more git documentation, and I have a lot of respect for Beej's Guide to Network Programming. However he really needs to work on his commit hygiene. I get that this is a one-man project, but still it's pretty atrocious: https://github.com/beejjorgensen/bggit/commits/main/. This does not set a good example.
I usually refer people to https://cbea.ms/git-commit/.
Wait do people write all their commit messages with `-m`? No wonder they're always so bad.
I use an editor to write commit messages because it lets me take my time, to format them, to edit them after the initial draft.
If I know the message will be under 50 characters, I might use `-m`, but the rest of the time I want an editor.
Always relevant: https://cbea.ms/git-commit/