What you can do after this lesson
You will write commit messages that help real people, including the person most likely to read them: you, six months from now, trying to work out why a line exists. There is no single official standard, but the conventions here are widely used, and the Git project's own documentation and the Pro Git book describe a very similar style.
Why messages matter
The diff shows what changed. Only the message can say why. When you run git log, git blame or git bisect, the messages are the readable index to the project's past. Compare these two histories:
5d2a1b0 stuff
1c9be33 update
8f01aa2 fix5d2a1b0 Round cart totals to two decimal places
1c9be33 Add free delivery over the minimum order
8f01aa2 Fix crash when the basket is emptyThe second tells a story you can skim. The hashes here are illustrative; they differ in any real repository.
The structure
Short summary in the imperative, about 50 characters
A body that explains why the change was needed, what problem it
solves and anything surprising. Wrap lines near 72 characters.
Mention related issues here, for example "Refs #12".- Subject: one line, around 50 characters. Many tools truncate longer ones. No full stop at the end.
- Blank line: it separates subject from body. Git and many tools rely on it.
- Body (optional): explain motivation and context in plain sentences. Wrap near 72 characters so it reads well in terminals.
The 50 and 72 figures are conventions, not rules enforced by Git. Treat them as guides.
Imperative mood
Write the subject as a command: "Add", "Fix", "Remove", "Rename", as if completing the sentence "If applied, this commit will ... ". Git itself writes messages that way ("Merge branch ...", "Revert ..."). It makes the log read consistently. Do not write "Added" or "Fixing" unless your team's convention says otherwise.
Writing a body from the command line
Use -m more than once; each becomes a paragraph:
git commit -m "Add z file" -m "This explains why the file exists, in a second paragraph."
git log -1 --format=fullercommit 548f87f169ff879ca96b094a23fc4e8a8ace98a4
Author: Asha Rao <asha@example.com>
AuthorDate: Tue Nov 10 10:00:00 2026 +0000
Commit: Asha Rao <asha@example.com>
CommitDate: Tue Nov 10 10:00:00 2026 +0000
Add z file
This explains why the file exists, in a second paragraph.Without -m, git commit opens your editor, which is more comfortable for longer messages. Lines starting with # in that editor are comments and are removed. This is example output; hashes and dates differ.
What makes a good body
Good bodies explain:
- The problem: "Orders over 100 were charged delivery by mistake."
- The approach, if not obvious: "Compare against the order total before delivery is added."
- Trade-offs or alternatives rejected: "A discount code was considered but adds a new table."
- Side effects: "Invoices created earlier are unchanged."
Avoid repeating the diff ("changed line 12 to 13"), and avoid blame or jokes that age badly.
Small, focused commits make messages easy
If you cannot describe a commit in one short sentence, it probably does two jobs. Split it. Stage related changes together with git add file, and for pieces of one file, git add -p lets you pick hunks interactively. Separate commits for "fix the bug", "reformat the file" and "rename the helper" are far easier to review and revert than one commit doing all three.
Templates and checks
Git can show a template whenever you commit. Put the structure above in a file and point commit.template at it. In a test, the editor opened with this content:
Short summary (about 50 characters)
Why this change is needed.Git also refused to commit when the template was left unchanged: Aborting commit; you did not edit the message. You can set this up with git config commit.template ~/path/to/template.txt.
To catch sloppy whitespace before committing, run:
git diff --cached --checkg.txt:1: trailing whitespace.
+trailing Teams sometimes enforce message rules with a commit-msg hook (the hooks lesson shows one) or with checks on pull requests.
Team conventions
Some projects add structure on top: a prefix such as fix: or feat:, an issue reference such as Refs #12, or a required sign-off line. If your project has a convention, follow it, even if you would choose differently. Consistency helps tools and readers more than any one style does. For GitHub, keywords such as closes #12 can link a commit or PR to an issue, as the previous lessons mentioned.
Fixing a message afterwards
If the commit is the latest and unpublished, git commit --amend rewrites the message. For older unpublished commits, an interactive rebase with reword does it. On shared history, leave the message and write a better one next time.
Common mistakes
- Messages like "fix", "update", "stuff". They carry no information.
- Subjects that run on for a paragraph. Put detail in the body.
- Writing what instead of why. The diff already shows what.
- Committing everything in one go. Split by purpose.
- Including secrets or private details in a message. History is permanent.
Exercise
- Look at your last five commit messages with
git log --oneline -5. Rewrite each in your head as an imperative subject under 50 characters. - Make a commit that has both a subject and a body, using two
-moptions. - Create a template file and set
commit.template. Rungit commitand check that it appears.
Show one possible answer
git log --oneline -5
echo change >> notes.txt
git add notes.txt
git commit -m "Clarify the install steps" -m "New readers were skipping the PHP version check, so it now comes first."
git log -1 --format=%BFor the template, write a file with a subject placeholder and a body prompt, then run git config commit.template path/to/file.
Next: Team workflows: feature branches, GitHub flow and trunk-based development.
Key points
- A commit message is a note to a future reader, often you, explaining what changed and why.
- A widely used convention is a short subject line of about 50 characters, a blank line, then a body wrapped near 72 characters.
- Write the subject in the imperative, like an instruction, and spend the body on why rather than a repeat of the diff.
- One commit should do one thing; messages are easier when changes are focused.
- Teams may add conventions such as issue numbers or prefixes; follow the project's rules.