Skip to content
Tutorials Center
My learning

Topics

Lesson 56 of 78 ยท Customizing and Automating Git

Conventional Commits and Changelogs

Write structured commit messages with Conventional Commits, derive the next semantic version from history, enforce the format with a hook and generate a changelog.

A commit message is read far more often than it is written: in git log, in code review, during a bisect, and by whoever prepares the next release. Most teams start with free-form messages ("fix stuff", "wip", "update") and discover too late that nobody, including a script, can tell from the history what changed for users. Conventional Commits is a small convention that fixes this. It gives every message a predictable shape, which in turn lets tools decide the next version number and write the release notes for you.

In this lesson you will learn the format, how it connects to semantic versioning, how to enforce it with a commit-msg hook, and how to build a changelog from history using nothing but git log. Along the way you will use the log formatting tools from Log and Show and the hooks from Git Hooks.

The message format

A conventional commit has a type, an optional scope, a short description, and optionally a body and footers:

TEXT
<type>(<scope>): <description>

<body>

<footer>

The first line is the subject. Typical types are:

Type Meaning Version effect
feat A new feature for users minor
fix A bug fix patch
docs Documentation only none
style Formatting, no code change none
refactor Code change that neither fixes nor adds none
perf Performance improvement patch (usually)
test Adding or fixing tests none
build, ci Build system or pipeline changes none
chore Maintenance that fits nowhere else none

The scope names the part of the project in parentheses: feat(search): add fuzzy matching. A breaking change, one that makes existing users change their code, is marked in either of two ways: an exclamation mark before the colon (feat(api)!: remove v1 endpoints) or a footer that starts with BREAKING CHANGE: followed by a description.

TEXT
feat(auth)!: require email verification before login

Accounts created before this release are verified automatically.

BREAKING CHANGE: the /login endpoint now returns 403 for unverified users.
Refs: #482

Write the description in the imperative mood and lowercase, without a final period: "add", not "added" or "adds". Keep the subject near 50 to 72 characters and put the reasoning in the body, as explained in Commits.

Why bother: semantic versioning

Semantic versioning (SemVer) numbers releases as MAJOR.MINOR.PATCH. You increase MAJOR for incompatible changes, MINOR for new backward-compatible functionality and PATCH for backward-compatible bug fixes. Conventional Commits was designed to line up with it exactly:

flowchart TD
  C["Commits since the last tag"] --> B{"Any breaking change?"}
  B -- yes --> MAJOR["Bump MAJOR<br/>1.4.2 to 2.0.0"]
  B -- no --> F{"Any feat?"}
  F -- yes --> MINOR["Bump MINOR<br/>1.4.2 to 1.5.0"]
  F -- no --> X{"Any fix or perf?"}
  X -- yes --> PATCH["Bump PATCH<br/>1.4.2 to 1.4.3"]
  X -- no --> NONE["No release needed"]

The highest-impact commit since the last tag decides the next version number.

Because the rule is mechanical, a script can follow it. The example below builds a small history, then lists the commits grouped by type and computes the next version from the latest tag.

Bash Group commits by type and compute the next version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git log --grep matches the pattern against the message, and ^feat anchors it to the start of a line. With one feat and two fix commits since v1.4.2, the next version is v1.5.0. If one of the commits had carried a BREAKING CHANGE: footer, the answer would be v2.0.0.

SemVer versions below 1.0.0 are "initial development": anything may change. Many projects keep a 0.x version and bump the minor number for breaking changes during that phase.

Enforcing the format with a hook

A convention nobody checks decays within a month. The cheapest guard is a commit-msg hook: Git runs it after the message is written and rejects the commit if the script exits with a non-zero status. The hook receives the path of the message file as its first argument.

Bash A commit-msg hook that rejects bad messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Hooks live in .git/hooks, which is not shared by git clone. To give the whole team the same check, store the script in the repository (for example .githooks/commit-msg) and run git config core.hooksPath .githooks, or use a hook manager. Remember that a hook can be skipped with --no-verify, so also run the same check in CI against pull request titles. The longer treatment of sharing hooks is in Git Hooks.

Squash merges and pull request titles

Many teams merge pull requests with squash, which turns the whole branch into one commit on main (see Merging Branches). In that case the commit that matters is the squash commit, and its subject is normally the pull request title. So enforce the convention on the title, and developers can keep messy work-in-progress commits on their branches. Rebasing and squashing locally with interactive rebase achieves the same before you push.

Generating a changelog

A changelog tells users what changed between versions. The best ones are written for humans, grouped by kind of change, and link to the commits or issues. With conventional commits you can generate a first draft automatically and then edit it.

The idea is to loop over the range between two tags and print a section per type. This version uses only git log and sed:

Bash Build a Markdown changelog from commit history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The loop prints newest versions first, as changelogs do. Real tools do the same with more polish. git-cliff, conventional-changelog, release-please and semantic-release read the same message format, pick the next version, update the changelog file, create the tag and (for some) the release on your hosting platform. They are configured in the repository, so every contributor gets the same result.

A few rules keep a changelog useful:

  • Describe the effect on users, not the implementation. "Fix crash when the file is empty" beats "handle null".
  • Always show breaking changes prominently, with migration advice.
  • Link each entry to a pull request or issue.
  • Do not paste the raw log of a release. Edit the draft.

The release steps themselves (tagging, notes, signing) are practiced in Release Process and Tags.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which commit message follows Conventional Commits and marks a breaking change?

    A breaking change is flagged with an exclamation mark before the colon, or with a BREAKING CHANGE: footer. The type and colon format must also be valid.
  2. 2. The last tag is v2.3.4. Since then there are two fix commits and one feat commit, none breaking. What is the next SemVer version?

    A new feature raises the minor version and resets the patch number. The fixes do not matter once a feat is present.
  3. 3. Why is a commit-msg hook alone not enough to enforce the convention for a team?

    Files in .git/hooks are local. Share the script through core.hooksPath or a hook manager, and run the same check in CI to catch bypasses.
  4. 4. Which command lists only the feat commits between two tags?

    A range a..b selects commits reachable from b but not from a, and --grep filters their messages. The caret anchors the pattern to the start of the line.
  5. 5. With squash merges, which text should follow the convention?

    The squash commit is the one that lands on main, and most platforms use the pull request title for its subject.

Summary

  • Conventional Commits gives each message a type, an optional scope and a description: type(scope): description, with ! or a BREAKING CHANGE: footer for breaking changes.
  • The types map to SemVer: breaking changes bump MAJOR, feat bumps MINOR, fix and perf bump PATCH.
  • git log <old-tag>..HEAD --grep='^feat' groups commits by type, and git describe --tags --abbrev=0 finds the last release.
  • A commit-msg hook can reject bad messages; share it through core.hooksPath and repeat the check in CI.
  • With squash merges, enforce the convention on pull request titles.
  • Generate a changelog draft from the log (or use git-cliff, release-please, semantic-release), then edit it for readers.

Next: GitHub Basics