Writing the perfect git commit message

Writing the perfect git commit message
Writing the perfect git commit message

Commit messages to come in all forms and sizes. Clean git history is not a priority in many codebases, but don't be mistaken. It is essential. It is a way to keep your commit messages uniform and easy to read.

Conventional commits are a way of writing commit messages that have been around for a long time. And here is an example of what one looks like:

01feat(scope): add magical unicorn
02^--^^-----^ ^------------------^
03| | |
04| | +-> Summary in present tense. Starting with add, remove, update, do. Think about: If I commit this, my code would .... add magical unicorn
05| |
06| +-> optional scope of the commit, component-name, container
08+-------> Type: chore, docs, feat, fix, refactor, style, or test.

Commit type

The developer should write the commit from the user's perspective, not the developer's. Slight nuance, but it makes a difference.

  • `feat`: New feature for the user (not a feature to the code, or ci, ...)
  • `fix`: Bugfix for the user (not a fix to build something, ...)
  • `docs`: Changes to the documentation
  • `style`: This could be the styling of the code or styling changes in general. Does not change any functionality.
  • `refactor`: Refactoring production code. For example: Renaming a variable
  • `test`: Only changes current or new tests. Does not change the production code
  • `chore`: Does not impact production.

Scope (optional)

You may provide a scope after a type, but it must consist of a noun describing a section of the codebase. feat(datepicker):

The commit message

Writing a good commit message is food for discussion, and according to conventional commits (and myself), you should write the commit message in the present time.

An excellent way to write a message is to fill in the sentence:

If I commit my code, it will ... (add a magical unicorn)feat(forest): add a magical unicorn

The message body (optional)

We have covered most ways of writing commit messages, but a message body can still be filled in.

The body can include the motivation for the change and contrast this with previous behaviour.

  • The body is the place to mention issue identifiers and their relations

Example `closes #33`

The body footer (optional)

The footer should contain any information about Breaking Changes.

Breaking Changes should start with the word BREAKING CHANGES: followed by space or two newlines.

A breaking change can be part of commits of any type.

01feat(forest): add magical unicorn
03close #1337
04BREAKING CHANGES: We removed horses, because they don't get allong

Semantic versioning

  1. fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
  2. feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
  3. BREAKING CHANGE: a commit that has a footer, or appends ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.