development
Write Better Git Commit Messages with Conventional Commits
3/21/2022Probably most developers know the struggle of writing good and consistent git commit messages. If you have the same problem you should take a look at the Conventional Commits specification.
I've been writing commits according to this specification (with some additions) for a while now and the commit history of all projects became a lot more consistent and easier to understand.
The basic structure of a „conventional commit message“ is
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
with the following parts:
| Description | Examples | |
|---|---|---|
| type | the commit type | „feat“, „fix“, „chore“, … |
| scope (optional) | a scope to group commits for a specific topic | name of a feature, „api“, „auth“, … |
| description | a short, lowercase description of the commit in present tense | „add readme file“ |
Commit Types
Although the Conventional Commits specification only explicitly includes the feat and fix types, the documentation says that other types are allowed. There are a few variants of allowed types. Here are the ones I use:
| Type | Description | Example Commit |
|---|---|---|
| feat | a new feature or enhancement to the codebase | feat(api): add system status endpoint |
| fix | patch for a bug | fix(auth): unhandled exception for duplicate usernames |
| bump | version update | bump: version 1.0.2 |
| ci | continuous integration changes | ci: add unit tests to workflow |
| docs | changes to the documentation | docs: create readme |
| localize | localization/translation updates | localize(login): add German translation for login btn |
| perf | performance improvements | perf(search): improve sql query |
| refactor | refactoring, improved code with the same functionality | refactor: move duplicate methods to shared parent class |
| style | code style changes | style: correct indentation |
| test | adding or updating tests | test(auth): add jwt module unit test |
| content | new or updated content (e.g. for a git-based CMS) | content(blog): add conventional commits article |
| chore | anything else (like dependency updates, db dumps, ...) | chore(composer): update dependencies |
For more information and the full specification please visit the conventionalcommits.org website!