The previous module ended with an uncomfortable diagnosis: the task-manager team now has an impeccable process — forks, pull requests, reviews, protected branches, continuous integration — and it can still end up with a history nobody is able to read. We start putting that right at the most everyday and most neglected point of all: the commit message.

This lesson finally settles two of the course's debts. In lesson 02-04 we learnt to commit changes with git commit -m and said that message conventions would arrive here. In lesson 06-01 we wrote a commit-msg hook that demanded a ticket in the form GT-NNN, but we were validating a convention we had not yet explained. And in 07-06 we validated that same convention in CI. It is time to explain where all of that comes from.

It is worth understanding the scale of the matter before we start. A developer writes between five and twenty commit messages a day. They are the only prose the project produces systematically, the only text that survives refactors, and the only one that will still be there when the original author has left the company. The code says what the program does; the history is the only place where why it does it that way can be written down.

1. Who a commit message is written for
2. The why matters more than the what
3. Anatomy of a good message
4. The subject line: the seven rules
5. The body: motivation and context
6. The footer: references, tickets and co-authorship
7. Bad messages and their good version
8. Conventional Commits
9. BREAKING CHANGE and the derived version
10. Templates with commit.template
11. Writing in the editor, not with -m
12. Enforcing the convention: hook and CI
13. The language of the message

There is an intuitive and wrong answer: "for me, so I remember what I did". It is wrong because you, a week from now, will not need the message: you will have the context fresh. The message exists for three readers who do not have it.

Reader 1: you, two years from now. You remember nothing of the context. Not the meeting where that was decided, nor the client who complained, nor the browser limitation that forced you into something odd. The commit is all that is left.

Reader 2: whoever runs git blame on an odd line. It is the most frequent case and the most valuable. Somebody finds an absurd condition in app.js:

Their first impulse will be to delete it. In lesson 06-03 we saw that git blame answers which commit introduced that line. If that commit says fixes, the reader will delete the condition and reintroduce the bug. If it says Avoid the date filter on Safari 14: its Intl.DateTimeFormat returns the time zone in a format that breaks parsing, they will not delete it. The quality of the message decides whether the bug comes back.

Reader 3: whoever reviews your pull request. In lesson 07-02 we saw that reviewing well requires understanding the intent before the diff. A PR with atomic, well-described commits is reviewed commit by commit and in half the time. A PR with eight commits called wip, wip2 and now it works forces the reviewer to read a giant diff with no guidance at all.

There is a fourth reader that is also a machine: the tools that generate changelogs, derive versions and filter the history. That is what section 8 is about.

This is the central idea of the whole lesson, and the hardest one to take on board.

The diff already says the what. It is there, complete, exact and for ever. git show displays it with character-level precision. A message that says Change the button colour to blue when the diff says - color: #c00; / + color: #06c; is redundant: it does not add a single bit of new information.

What the diff can never tell you:

Compare these two messages about exactly the same diff of task-manager:

The first is information that was already in the diff. The second contains four facts that are nowhere else in the repository: where the old value came from, which specific bug it caused, how the new one was chosen and why it is not higher. Two years from now, when somebody proposes lowering it again "because 30 seconds is outrageous", that message is the answer.

The rule: if your message can be worked out by reading the diff, you have not written the message yet.

Git imposes no format, but it does treat the text in a structured way, and almost every tool in the ecosystem assumes the same convention. The canonical structure has three parts:

The blank line between the subject and the body is not decoration: it is syntax. Git uses the first line as the subject in git log --oneline, in %s of --pretty, in the subject of the emails produced by git format-patch and in the default title of a pull request. If you skip it, the whole message becomes the subject:

All the text run together, and --oneline rendered useless.

It is not an arbitrary magic number: it is the practical limit for git log --oneline, a hosting platform's commit list and git shortlog to fit on one line without being truncated. Hosting platforms cut off visually at around 72 characters, and GitHub warns you from 50.

If it does not fit in 50 characters, it is nearly always one of two things: the commit does too many things (we will see this in lesson 08-02) or you are putting into the subject what belongs in the body.

Write as if you were giving an order to the repository. The infallible test is completing this sentence:

"If applied, this commit _______"

It is not a whim: Git itself writes that way. Merge branch 'x', Revert "...", Initial commit. If your messages use another tense, the history mixes two voices.

It is a title, not a sentence. And in 50 characters, one character counts.

Unless you use Conventional Commits (section 8), where the usual convention is lower case after the colon. Pick one and be consistent.

Fix the error says nothing. Fix the deletion of tasks with an attachment does.

Change app.js is useless: git log --stat already says that. The scope, if you need one, goes with the Conventional Commits syntax.

Add the filter by label and fix the footer margin describes two independent changes. Lesson 08-02 develops this idea in depth.

The body is optional for a trivial change and mandatory for any non-obvious change. It is wrapped manually at 72 columns for a very specific reason: git log indents the body with four spaces, so 72 + 4 = 76, and it fits in an 80-column terminal without Git rewrapping the text (it does not: Git never reformats your message).

A useful body answers these questions, not necessarily all of them:

1. What was the problem or the need? The previous state and why it was not good enough.
2. Why this solution? And above all, which alternatives were discarded.
3. What side effects does it have? Performance, compatibility, migrations.
4. What does this change NOT do? Setting the boundaries is as useful as describing.
5. What do you need to know in order to review it? A link, a measurement, a command to reproduce it.

A complete example, about a real change to task-manager that Carla made:

Notice what it contributes that is not in the diff: the specific measurement, the discarded alternative with its reason, the expiry date of the migration code and the explicit limit of the change.

The footer (trailer in Git's terminology) is a block of Key: value lines at the end of the message, separated by a blank line. Git understands it natively through git interpret-trailers, and the platforms interpret it too.

Co-authorship deserves a special mention, because it solves a real problem for the team. When Ana and Bruno pair-program, the commit is signed only by whoever types it, and git blame (lesson 06-03) attributes everything to that person. With the trailer, the platforms recognise both:

An important detail: the Co-authored-by line must go at the end, preceded by a blank line, and the email must be the one the person has registered on the platform. Otherwise the name shows up but is not linked to the account.

You can automate it with git interpret-trailers:

This table collects real messages from the early history of task-manager, back when the team had no convention, alongside what they should have been.

Notice the pattern: bad messages are nearly always short out of haste or dependent on context that evaporates ("yesterday", "what Carla mentioned", "now it works").

So far we have talked about prose for humans. Conventional Commits is a convention that additionally makes the subject machine-readable, without losing human readability. It is the one used by the commit-msg hook we wrote in lesson 06-01.

The format:

Examples on task-manager:

The scope in brackets is free-form and each project defines its own. On task-manager the team agreed on: filters, sync, list, ui, css, readme, deps, ci. A stable scope turns git log --oneline | grep '(sync)' into a useful query.

1. Filtering the history is trivial. git log --oneline --grep '^feat' gives you every new feature.
2. Automatic changelog. Tools such as git-cliff, standard-version or semantic-release group the commits by type and generate CHANGELOG.md with no human intervention.
3. A derived SemVer version. This links directly to lesson 05-05: there we agreed on MAJOR.MINOR.PATCH and annotated tags, but we decided the number by hand. With Conventional Commits, the number is derived from the history.
4. Granularity discipline. If you do not know which type to use, it is nearly always because the commit does more than one thing.

Suppose that since v1.4.0 the history of task-manager contains:

There is one feat and no BREAKING CHANGE, so the next version is v1.5.0. If there had only been fix commits, it would be v1.4.1. If there had been neither feat nor fix, there would be no version to release.

A compatibility break is a change that forces whoever consumes your code to do something. In SemVer it raises the MAJOR number, and it is the only case where automatic derivation cannot fail without serious consequences.

It is marked in two equivalent ways:

Form 1 — with ! after the type or the scope:

Form 2 — with a trailer in the footer (which lets you explain the migration):

The second is clearly better: the message includes the migration guide, and the changelog tools copy it verbatim into the breaking changes section. Use both at once if you want the ! to be visible in --oneline.

Beware of squashing. If you integrate pull requests with squash merge (we will look at this in depth in lesson 08-02), the message that counts for the derivation is the one on the squashed commit, not the ones on the branch. A BREAKING CHANGE hidden in the third commit of a branch disappears if the squash title is feat: assorted improvements. It is a strong argument for reviewing the squash title before merging.

The cheapest way to get a whole team writing better messages is to put the reminder in front of their eyes at the exact moment. That is what commit.template does: a file whose content preloads the editor every time you commit.

Create the file in the repository, so that Ana, Bruno and Carla all use the same one:

Content of .gitmessage:

And it is switched on with:

Three details that matter:

• Lines starting with # are discarded when you save, so the instructions never reach the history. The comment character can be changed with core.commentChar if you need a literal # (for example, to write #123).
• commit.template is not versioned by itself. The .gitmessage file is indeed in the repository, but the configuration that activates it lives in .git/config, which as we saw in lesson 01-05 is local. Document the git config --local commit.template .gitmessage in the README.md, or add it to the project's bootstrap script.
• The template does not apply with -m. Only when Git opens the editor. Which brings us to the next section.

git commit -m "..." is convenient and that is why it is everybody's default habit. It is also the structural cause of bad messages, for three reasons:

1. The terminal quote pressures you into being brief. Typing a paragraph inside quotes in the shell is awkward, so you do not type it.
2. You cannot see the context. The editor shows you, commented out, the list of modified files. Very often that is where you discover you have staged a file you did not want.
3. There is no review. With -m you press Enter and that is that. In the editor you read what you have written before saving.

Compare:

When you run plain git commit, the editor (core.editor, lesson 01-06) opens with the template and with this underneath:

And with -v you also get the full diff inside the editor, which is the best possible aid for writing the why:

Turn it on for good:

When -m is fine: for genuinely trivial commits (docs: fix a typo), in scripts, and for the --fixup commits of lesson 05-02, which are going to disappear in the rebase.

If the message is long and you would rather not depend on the editor, there is a clean alternative:

A convention that is not checked erodes within three weeks. In lesson 06-01 we wrote a commit-msg hook; now that the convention has been explained, here is the full, commented version.

Remember from lesson 06-01 the three requirements for it to work:

And remember too the warning that lesson 07-06 turned into a principle: a client-side hook is not a control. git commit --no-verify skips it. That is why the same check has to be in CI, where nobody is in charge:

An important nuance that is always forgotten: if your integration policy is squash merge, validating the branch's individual commits makes little sense — they are going to disappear — and what you have to validate is the title of the pull request, which will be the subject of the squashed commit. Which of the two policies is the right one is exactly the question the next lesson answers.

It is a discussion that comes up in every team and it has a single correct answer: pick one and stick to it.

What is genuinely bad is not choosing wrongly: it is not choosing. A history where half the subjects read feat: add the filter by label and the other half say exactly the same thing in the team's own language is harder to search (--grep stops working), harder to read and conveys carelessness.

A very common compromise in teams that do not work in English is to keep the type and the scope in English (because they are keywords of the convention and the tools understand them) and to write the description, the body and the trailers in the working language (because it lets people explain the why without impoverishing it). On task-manager the four of them work in English, so the team agreed, and wrote it in the README.md: everything in English, from the type to the last trailer.

Diego, the outside contributor, found the decision written in the README.md of his fork before opening his first pull request. That is where it belongs: in the repository, not in anyone's head.

Mistake 1: describing the what instead of the why. It is the dominant mistake. Change the value to 30 adds nothing; The 5 s value came from the prototype and no longer covers uploading attachments adds everything. Acid test: if the message can be worked out from the diff, you have not written the message yet.

Mistake 2: forgetting the blank line after the subject. It breaks --oneline, the PR titles and %s in --pretty. It is syntax, not style.

Mistake 3: ephemeral context. "As we discussed yesterday", "what Carla asked for", "according to this morning's email". Six months from now they mean nothing. Write the content, not the pointer.

Mistake 4: linking to an external system instead of summarising. See GT-134 leaves you stranded the day the ticket tracker is migrated or somebody reads the history without access to it. Reference the ticket as well as summarising, never instead of.

Mistake 5: process messages. Changes requested in the review, Now it works, Another try. They describe your working day, not the code. Squash them with --fixup and rebase -i --autosquash (lesson 05-02) before publishing.

Mistake 6: believing it can be fixed later. The message of a published commit can only be changed by rewriting the history, and that clashes with the golden rule of lesson 05-01. A bad published message is permanent. (If you have not pushed it yet, git commit --amend fixes it; lesson 09-02 develops the undo cases.)

Mistake 7: applying Conventional Commits halfway. Half a dozen commits with feat: and the rest in free prose produces the worst of both worlds: the discipline of the convention with none of its automatic benefits, because the changelog comes out incomplete.

Tip 1: write the message before the code. It sounds odd and it works. If you cannot summarise in one line what you are about to do, the change is not properly scoped yet.

Tip 2: turn on commit.verbose today. git config --global commit.verbose true puts the diff inside the editor. It is the cheapest quality improvement in the whole module.

Tip 3: read your own history once a month. git log --oneline -30. If you do not understand your commits from three weeks ago, you have a problem that will only grow.

Tip 4: use git shortlog -sn --no-merges and git log --oneline --grep. If your queries against the history return nothing useful, it is a sign that the messages are not useful either.

Tip 5: in reviews, review the messages too. It is perfectly legitimate to ask in a PR for "rewrite the message of the second commit". It is the only way the convention survives.

Tip 6: the template in the repository, not in your $HOME. That way Diego has it as soon as he clones the fork.

For each of these real messages from the early history of task-manager, write the good version: a subject in the imperative of ≤50 characters and, where the case calls for it, a body. Invent whatever plausible context is missing.

1. fix css
2. update app.js
3. Added the search box and fixed the footer margin
4. Now it really works
5. Bump the dependency

In a test repository:

1. Create a template file .gitmessage with the Conventional Commits structure and activate it with commit.template at local level.
2. Turn on commit.verbose.
3. Install the commit-msg hook from section 12 in .githooks/ and configure core.hooksPath.
4. Check that it rejects assorted fixes, that it rejects feat: add the filter (the ticket is missing) and that it accepts feat(filters): add the filter by label with Refs: GT-134 in the body.
5. Show that --no-verify dodges it and explain which barrier would stop it.

Given this history since the v2.3.1 tag of task-manager:

1. Which SemVer version should be released and why?
2. Write the complete message for commit 9182b3c with its BREAKING CHANGE trailer and its migration guide.
3. Write the git log command that would extract only the feat commits from that range.
4. If the team integrated this branch with squash merge and the squash title were feat: sync improvements, which version would the tool derive? What problem does that reveal?

Solution 1:

Solution 2:

--no-verify is a client-side option: it does not travel over the network and the server never finds out it was used. The barrier that does stop it is the CI one (section 12) declared as a required check on a protected branch, exactly as we saw in lesson 07-06. The local hook is a convenience for the developer; the protected branch is the control.

Solution 3:

1. It should be v3.0.0. The presence of feat(api)! marks a compatibility break, and in SemVer that raises the MAJOR number and sets MINOR and PATCH to zero, regardless of there also being two feat commits and a fix. The break always wins.

2.

3.

And to locate the breaks specifically, since they may be in the body:

4. The tool would derive v2.4.0 (one feat, no visible break), because the BREAKING CHANGE was in the body of a commit that the squash made disappear. The result is serious: a change that breaks every consumer is released as a MINOR, and those consumers upgrade trusting SemVer's compatibility guarantee.

What it reveals is that the integration policy is not an aesthetic decision: it changes which messages survive on the mainline and, therefore, which information stays available to people and to tools. If you squash, the squash title must be validated with the same rigour as a commit, and the relevant trailers must be propagated to it. That policy is exactly the topic of the next lesson.

The essentials of this lesson:

• A commit message is written for three readers with no context: you two years from now, whoever runs blame on an odd line and whoever reviews your PR. And for a fourth that is a machine.
• The diff already says the what; the message exists for the why. If your message can be worked out from the diff, you have not written it yet. What only fits in the message is the motivation, the discarded alternatives, the side effects and the limits of the change.
• The anatomy is syntax, not decoration: a subject of ≤50 characters in the imperative and with no full stop, a mandatory blank line, a body at 72 columns, and a footer with trailers (Refs, Co-authored-by, BREAKING CHANGE).
• Conventional Commits makes the subject machine-readable without it ceasing to be human-readable: type(scope): description. In exchange for a minimal discipline, you get history filtering, an automatic changelog and, linking back to lesson 05-05, the SemVer version derived from the history itself.
• A template with commit.template in the repository puts the reminder in front of your eyes at just the right moment. And writing in the editor with commit.verbose instead of with -m improves quality more than any other single measure.
• The convention is held up by the commit-msg hook of lesson 06-01 for the developer's convenience and by the validation in CI on a protected branch from lesson 07-06 for what is non-negotiable, because --no-verify exists.
• The language is chosen once, written down in the README.md, and never argued about again.

One loose end remains that exercise 3 has brought into view: an excellent message is worth nothing if the integration policy erases it. And that policy — merge, squash or rebase — is exactly the decision we left open in lesson 07-04 about GitHub Flow.

We settle it now, along with everything else that makes a history readable, bisectable and reversible, in lesson 08-02: Keeping a Clean History.