Writing a Commit Message Worth Reading
Every commit carries a message, and most beginners treat it as a toll: type something, get past it, move on. Six weeks later they are staring at a list that says update eleven times.
The diff already records what changed. The message exists to record why — and the person guaranteed to need that is you, in four months, trying to work out why a line you wrote today exists at all.
The shape
A commit message is a short first line, and optionally a blank line followed by as much explanation as the change deserves.
git commit -m "Fix the meeting time on the home page" git commit -m "Move the sightings list into its own file" -m "The home page was getting long and the club wants to add photos next month, which would have made it much worse."
The first line is a summary: aim for under about fifty characters, capitalize it, and leave off the full stop. Short enough that it reads well in a list, because that is where you will see it — the one-line log view in the next chapter shows nothing but these first lines.
Imperative mood, and why it is not fussiness
Write the first line as an instruction: "Add the sightings list", not "Added" and not "Adds".
The reason is boring and practical. Git generates messages itself for some operations — merges and reverts, both of which you will meet — and it writes them in the imperative. Matching that keeps a log reading as one consistent voice instead of three. A useful test: the line should complete the sentence "if applied, this commit will…".
What belongs in the body
Most commits need no body. When one does, it is because the change has a reason that is not obvious from reading it: the alternative you tried first and abandoned, the constraint that forced an odd-looking solution, the thing that will look like a mistake to whoever reads it next.
What does not belong in the body is a description of the diff. "Changed line 42 of index.html" tells the reader something they can already see, and it costs the reader time to discover that.
The messages that help nobody
fix. update. changes. wip. asdf. final. Everyone has written all of them.
They are usually honest about one thing: the commit was too large or too vague to describe. When you genuinely cannot summarize a commit in one line, that is information — you are probably holding two commits, which is the subject of the next chapter.
One commit, one idea
The most useful test in this book: write the message in your head before you commit. If you cannot write it without the word "and", you are looking at two commits, and staging is what lets you split them.
Sandpiper's log so far reads as three plain English sentences: Add the club home page, Add basic styling for the home page, Fix the meeting time on the home page. Nothing clever, and someone who has never seen the project could follow it.
If Git opens an editor
Run git commit without -m and Git opens a text editor for the message. If you did not choose one, that editor is frequently Vim, and Vim does not tell you how to leave.
The escape: press Esc, type :wq, press Enter — write and quit. To abandon the commit instead, type :q! and press Enter. If you would rather use something familiar, set it once: git config --global core.editor "code --wait" for VS Code, or nano for something simple.
- "Nobody reads commit messages." The person who reads them most is their author, months later, usually while something is broken. On a shared project, reviewers read them constantly — that is Chapter 8.
- "The message should describe the code that changed." The code is in the diff and always will be. The message carries the one thing the code cannot: the reason it looks like that.
- "I will write good messages once the project is serious." The habit does not arrive on demand, and the early history is exactly the part nobody remembers later.
- "Long messages are better messages." Most commits need one clear line. A body is for a reason that is genuinely not obvious, and padding hides the commits where the body actually matters.
- Commit messages are the only durable record of intent in a project. The code says what it does; nothing else says why it does it that way.
- The one-line log view in the next chapter shows nothing but these first lines, so their quality is the readability of your entire history.
- The "can I write this without the word and" test is what keeps commits small enough that Chapter 4 can undo one mistake without undoing a whole afternoon.
Knowledge Check
What is the commit message for, given that the diff already exists?
- Recording why the change was made, which the diff cannot show
- Recording which files were touched, so they can be found again later
- Naming the person responsible, so questions reach the right author
- Describing what you intend to do in the next commit you make
Why write the first line in the imperative — "Add the sightings list" rather than "Added"?
- Because Git writes its own generated messages that way, so the log keeps one voice
- Because past tense messages are rejected by Git and the commit will fail
- Because the imperative form is shorter and therefore fits the fifty-character limit
- Because tools that read commit messages cannot parse the past tense correctly
You cannot describe your commit without using the word "and". What does that suggest?
- That it contains two ideas, and staging can split it into two commits
- That the message needs a body paragraph to explain the second half properly
- That the commit is too small and should be combined with the next one
- That Git will reject the commit for containing unrelated changes
Git opened an unfamiliar editor and you cannot get out. What is happening, and what do you do?
- You committed without
-mand landed in Vim: press Esc, type:wq, press Enter - The commit failed and the editor is showing the error, so the window must be closed
- Git is showing you the diff for review, and any key will dismiss it
- The repository is locked by another process, and the editor is a warning about it
You got correct