2 min read

Write Commit Like An Artisan

#git #devops #github

When I first started using Git as my code version control system, I tended to write commit messages however I liked.

However, I later stumbled upon a GitHub repository (I don’t remember which one) that had very clear commit messages. After some research, I discovered they were following the Conventional Commit standard.

Basically, they used this template for commit messages:

<type>[optional scope]: <description>
[BLANK LINE]
[optional body]
[BLANK LINE]
[optional footer(s)]

Here is the list of available type:

  • build (build system or external dependencies changes)
  • chore (maintain)
  • ci (CI configurations and scripts changes)
  • docs (documentation)
  • feat (feature)
  • fix (bug fix)
  • perf (improves performance)
  • refactor (neither fixes a bug or adds a feature)
  • revert (reverts a previous commit)
  • style (formatting, missing semi colons, etc.)
  • test (adding missing tests)

For a general guide:

  • type must be one of the options above.
  • scope is optional and indicates the specific place of changes.
  • ! is used before the semicolon for breaking changes.
  • description uses the present tense, does not end with a period, doesn’t capitalize the first letter, and explains “WHAT” changed.
  • body uses the present tense and explains “WHY” this change is needed.
  • footer provides additional information about linked issues or automatically “Closes” the issue.

For example, consider this commit message:

feat(admin)!: add filter for trashed data

Admin needs to manage/restore some trashed data.

Closes #13

The type is feat with scope admin and ! means this commit is a breaking change.

For further reference, check out their docs.

There are some tools to help you write good commit messages, check these out:

git-cz

  • git-cz. Semantic Git commits.
  • commitlint. Commitlint checks if your commit messages meet the conventional commit format.
  • commitlint.io. Lint commit messages online.
  • aicommits. A CLI that writes your git commit messages for you with AI.