Conventional Commits

I use Git to preserve the history of files in the vast majority of my projects but I am largely self-taught and thus feel like I periodically stumble onto fabulous features I didn’t know existed. For example, I was recently introduced to Conventional Commits which is a system for making more informative commit messages in version control systems.

I’ve long appreciated that “update” is not an ideal commit message but it can be hard to know which files should be staged into a commit or how much rambling information is useful in the long term. I’ve really enjoyed using this system to formalize both the frequency of my commits and the content of the associated messages.

Explanation

A conventional commit is one that uses one of the allowed “types” followed by a colon and then a short description of the specific content of that commit. As an example, your commit might look like:

feat: adding code tips to website

Making sure a commit fits only a single ‘type’ (and that all of the changes for a particular ‘type’ are in the same commit) has been a really useful scaffold for me. If it’s a breaking change you put a ! after the ‘type’ but before the :.

Example

I’m doing my best to be consistent in using this system going forward but this GitHub repository is one good example of my approach to this method.

Available ‘Types’

For reference, here’s the full list of official ‘types’ (and one bonus that I use sometimes). Note that I added fun symbols for each type that are not official.

Type	Symbol	Description
build		Changes to build system or external dependencies (e.g., Quarto extensions, etc.)
ci		Changes to continuous integration (“CI”) operations (e.g., GitHub Actions, etc.)
dev		Experimental changes that you may want to revisit in the future. This is my un-official addition!
docs		Changes to documentation
feat		Changes that introduce a new feature
fix		Changes that fix a bug
perf		Changes that affect (improve) performance
refactor		Changes that neither fix a bug nor add a feature. Used when the output of the code is unchanged but the way in which that output is reached has changed
style		Changes that do not affect the meaning of the code (e.g., white space, formatting, etc.)
test		Changes that create or modify tests