Semantic Git Commit Messages for Clarity and Structure
May 02, 2018
I recently found out about semantic Git commit messages—a method for structuring Git commits into logical chunks by using semantic labels. Inspired by Karma’s style guide for Git commit messages, the following semantic Git commits can greatly improve your Git log readability at a glance. They help to clarify the record of changes to a project and help focus commits into scoped segments.
Semantic Git commits start with a semantic tag and use an imperative voice. Git commit messages should be prefixed with one the following tags:
feat:- implement new features for endusers
fix:- bug fix for endusers (not a build-process fix)
docs:- update to project documentation
style:- update code formatting (indentation, tabs vs spaces, etc.)
refactor:- refactoring of code
test:- adding or updating tests
chore:- updates to build process
feat: tag should be used to identify new features or changes to production code that endusers will see. An example might be adding a method to sort posts based on popularity. It does not include changes to build process code, such as adding HTML minification in the build process pipeline.
"feat: add ability to view most popular posts"
fix: tag should be used to identify any bug fixes to production code. This includes any fix that would effect the enduser, not the build process.
"fix: check if file exists before attempting to unlink"
docs: tag is fairly straightforward and should be used to identify changes to the project documentation, either internal or client-facing.
"docs: add detailed installation instructions for Ubuntu"
style: tag should be used to identify changes made to the code style, which do not effect the enduser. Note that this is separate from the styling of user interfaces, which does effect the enduser. For example, a style change may indicate a change from using tab indentation to spaces.
For style updates that would effect the enduser, such as CSS changes, use the
feat: tag instead.
"style: convert from 4 space indentation to 2 spaces"
refactor: tag should be used to identify refactoring in the codebase. This includes changing variable names, combining or simplifying code, etc.
"refactor: rename ArticleController to PostController"
test: tag should be used to identify changes surrounding tests.
"test: add assertions for Collection update and destroy methods"
chore: tag should be used to identify changes to build scripts and other updates that do not alter production code. This might include dependency package updates or build script configuration edits.
"chore: update build script to webpack 4"