Chris Beams

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/.

This post has a similar tune: How to Write a Git Commit Message / The seven rules of a great Git commit message https://cbea.ms/git-commit/#seven-rules

I fully agree, this is my favorite write up on how a git commit messages should look like: https://cbea.ms/git-commit/

Follow this: https://cbea.ms/git-commit/ and this: https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits/ That way your "large change" becomes a collection of small, easy to reason about and well explained changes.

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.

Hello all, this is my first time ever really using Bash for scripting and I'm having a lot of fun. The tool aims to help newcomers write better commit messages, heavily inspired by the post "How to Write a Git Commit Message"[0] by cbea.ms. I hope you find this tool useful, and I'm open to any feedback! [0] - https://cbea.ms/git-commit/

Two other sources: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html https://cbea.ms/git-commit/

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.

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/

> The editor would give me too much freedom and I am likely to ramble! Please do! Context not included in the commit message or the code is lost forever. How to Write a Git Commit Message: https://cbea.ms/git-commit/

Very interesting read, thanks! Would you happen to know the justification behind "capitalize every commit subject line"[1]? I can understand finding it more appealing, but talking about it being as important as limiting the subject to 50 chars and not ending it with a period (which has a sensible justification), not as much. [1] https://cbea.ms/git-commit/#capitalize

> 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.

Ironically, the referenced article on how to write good git commit messages (https://cbea.ms/git-commit/) gives no "why" for most of its points. It lists 7 rules, of which 2, 3, 4, 5, 6 are simply declared without rationale.

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/198551ca54f6ff1c95c9357ccca9ae372988… https://github.com/git/git/commit/dee8a1455c8ad443ef59e0d5b7c168886e50… 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/aa0834a04e1d9d3ab81ecd4a4a138233e6e2… https://github.com/git/git/commit/38f865c27d1f2560afb48efd2b7b105c1278… 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…