Left ArrowBack

notes / web dev / git / commit message convention

commit message convention

A circle.

Git Commit Message Convention

Last Tended

Status: seed

Conventional Commits is a convention for adding human and machine readable meaning to commit messages.

Why

  • Improves a team's shared understanding of a codebase by better communicating what a commit did through:
    • structure,
    • clarity (through use of keywords) &
    • consistency.
  • Makes it easier to write automated tools on top of:
    • automatically generating CHANGELOGs,
    • automatically determining a semantic version bump (based on the types of commits landed) &
    • triggering build and publish processes based on commit type.

Structure

The convention structures a commit with 2 mandatory fields & 3 optional.

> <type>[scope]: <description>
> [body]
> [footer(s)]_

Examples

A bug fix

> git commit -m "fix: broken home link"_

A new feature with a breaking change

In Bash, you can use single quotes to write a message on multiple lines.

> git commit -m 'feat: add user-data API endpoint
>
> BREAKING CHANGE: remove user-name endpoint'_

A new feature with scope provided

> git commit -m "feat(user-profile): add user-avatar API endpoint"_
A wizard attempting to open a magic door at the base of a mountain.

Message Keywords

Key Word Indicates Correlates with SemVer
build Build system changes
ci CI configuration changes
docs Documentation changes
feat Introduce a new feature MINOR v1.0.0 -> v1.1.0
fix Patch a bug PATCH v1.0.0 -> v1.0.1
perf Performance improvements
test Add missing / correct tests
refactor
BREAKING CHANGE Introduce a breaking API change MAJOR v1.0.0 -> v2.0.0

Information about SemVer can be found here.

Where to Next?

A sci-fi robot taxi driver with no lower body