Commit Messages That Communicate Intent

A commit is not just a snapshot of code. It is also a message to the future — to teammates reading history, to yourself debugging a regression six months from now, to anyone trying to understand why the code is the way it is. The diff tells you what changed. The commit message tells you why.

Writing good commit messages is a professional habit. It costs almost nothing when you form it, and it pays off every time someone reads the history.

The subject line

The subject line is the first line of the commit message — what you write with -m. It should:

Be 50 characters or fewer — most tools truncate at 72, but 50 is the convention
Start with a capital letter
Not end with a period
Use the imperative mood — write “Add navigation toggle” not “Added navigation toggle” or “Adding navigation toggle”

The imperative mood is the convention because it matches how Git phrases its own messages: “Merge branch ‘feature’”, “Revert ‘Add broken feature’”. Reading history feels consistent.

Good vs. poor subject lines

Poor	Better
`fix`	`Fix broken link in tour card CTA`
`changes`	`Update hero copy for spring launch`
`wip`	`Add mobile nav toggle — keyboard accessible`
`asdf`	`Remove debug console.log from lightbox`
`made it work`	`Correct localStorage key collision between pages`

The poor examples tell you nothing when you see them in git log. The better examples tell you what changed and imply why, often without needing a body.

The body

For simple, self-evident changes, a subject line is enough. For anything requiring context — why you chose one approach over another, what the underlying problem was, what you tried first — add a body.

Leave a blank line between the subject and the body. The blank line is required for Git tools to treat them separately:

Fix contact form double-submission on fast clicks

The form's submit handler was firing twice when users clicked the
button quickly. Added a flag to track submission state and disable
the button immediately on first click.

Fixes the issue reported on the River Canyon tour booking page.

The body:

Wraps at 72 characters per line
Explains the why, not the what (the diff shows the what)
Describes the problem being solved, not just the solution
Can include relevant context: what you tried, what you decided against, links

What not to write

Do not describe what the diff already shows. “Changed the background color to green” is not a useful commit message if the diff already makes that obvious. Instead write why: “Use brand green for CTA hover state per design review.”

Do not use vague filler words. “Refactored,” “cleaned up,” and “improved” with no further explanation tell you nothing.

Do not commit unrelated changes and write a catch-all message. “Various fixes” usually means the commit contains several unrelated things that should have been separate commits. Use the staging area to split them.

Writing messages without the -m flag

If you omit -m, Git opens your configured editor for you to write the message. The editor shows a template with the files being committed commented out:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Changes to be committed:
#  modified: pine-ridge.txt

Type your message above the comment lines, save and close the file, and Git completes the commit. This approach is more convenient when you want to write a multi-line message with a subject and body.

Amending the last message

If you just committed with a typo or an unclear message and have not pushed the commit anywhere:

git commit --amend

Git opens your editor showing the previous message. Edit it, save, and close. The commit is replaced with an updated version. Module 04 covers --amend in detail — for now, know it exists for immediate corrections.

Exercise

Look at the last three commits in your git-practice repo:

git log --oneline

Evaluate each message against the conventions in this lesson. Would a reader who did not write the code understand what changed and why?

Now make a change to summit-challenge.txt — for example, add a difficulty rating and recommended gear list. Stage it:

git add summit-challenge.txt

Write a commit message that follows the subject-line conventions and, if the change needs more context, includes a body. Run git diff --staged first to remind yourself what you are about to commit, then:

git commit

(Without -m — this will open your editor. Write the message there.)

After the commit, run git log and read your message. Is it clear? Does it describe the why?

Recap

Subject lines should be 50 characters or fewer, capitalized, no period, imperative mood.
The imperative mood: “Add”, “Fix”, “Remove”, “Update” — not “Added”, “Fixing”, “Removes”.
Leave a blank line between the subject and body when writing a multi-line message.
The body explains why, not what. The diff already shows what.
Do not describe the diff. Do not use vague filler. Do not combine unrelated changes in one commit.
git commit without -m opens your editor for multi-line messages.

Next: git log — the command for reading your project’s history, with the flags and formats that make it genuinely useful.