Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Semantic Commit Messages

Semantic Commit Messages

See how a minor change to your commit message style can make you a better programmer.

Format: <type>(<scope>): <subject>

<scope> is optional

Example

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

More Examples:

  • feat: (new feature for the user, not a new feature for build script)
  • fix: (bug fix for the user, not a fix to a build script)
  • docs: (changes to the documentation)
  • style: (formatting, missing semi colons, etc; no production code change)
  • refactor: (refactoring production code, eg. renaming a variable)
  • test: (adding missing tests, refactoring tests; no production code change)
  • chore: (updating grunt tasks etc; no production code change)

References:

@YelemyahM

This comment has been minimized.

Copy link

YelemyahM commented Oct 15, 2018

Thanks it's very useful

@codebender828

This comment has been minimized.

Copy link

codebender828 commented Dec 7, 2018

Thanks. Good stuff

@adnanhz

This comment has been minimized.

Copy link

adnanhz commented Jan 9, 2019

Thanks

@lwwcas

This comment has been minimized.

Copy link

lwwcas commented Jan 15, 2019

Starting today, I'll start using it, thanks

@kevinjalbert

This comment has been minimized.

Copy link

kevinjalbert commented Jan 28, 2019

Wanted to drop this here as well: https://www.conventionalcommits.org

@tobyokeke

This comment has been minimized.

Copy link

tobyokeke commented Mar 15, 2019

thanks.

@keymusicman

This comment has been minimized.

Copy link

keymusicman commented Mar 23, 2019

How about intermediate commits? For example, a big feature that has not been completed by the moment but should be commited and pushed. How is it better to write such commit message?

@YourSouLi5Mine

This comment has been minimized.

Copy link

YourSouLi5Mine commented Apr 5, 2019

@keymusicman you can use wip for work in progress

@marinoguerieri

This comment has been minimized.

Copy link

marinoguerieri commented Aug 6, 2019

Thanks

@HoracioEspinosa

This comment has been minimized.

Copy link

HoracioEspinosa commented Sep 25, 2019

Thanks, i made a commit-msg hook with your semantic, thanks a lot

#!/bin/sh

branch="$(git rev-parse --abbrev-ref HEAD)";
commit_regex='((CDW-)([1-9][0-9])|((feat|fix|chore|refactor|style|test|docs)(((\w{0,15})))?))(:.\S.*)';
error_msg="Aborting commit. Your commit message format is invalid, please check the references."
commit_message="$1";

if ! grep -iqE "$commit_regex" <<<"${commit_message}"; then
echo "$error_msg" >&2
exit 1
fi

if [ "$branch" = "master" ]; then
echo "You can't commit directly to master branch"
exit 1
fi

if [ "$branch" = "develop" ]; then
echo "You can't commit directly to develop branch"
exit 1
fi

Captura de Pantalla 2019-09-25 a la(s) 10 05 57

You can test this regex expression here

@wirths

This comment has been minimized.

Copy link

wirths commented Nov 7, 2019

Thanks :-)
conventionalcommits.org is heavily inspired by Angular´s commit rules:
https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits

@rlocatelli9

This comment has been minimized.

Copy link

rlocatelli9 commented Dec 19, 2019

thanks bro

@avidal2433

This comment has been minimized.

Copy link

avidal2433 commented Jan 13, 2020

Thanks, i made a commit-msg hook with your semantic, thanks a lot

#!/bin/sh

branch="$(git rev-parse --abbrev-ref HEAD)";
commit_regex='((CDW-)([1-9][0-9])|((feat|fix|chore|refactor|style|test|docs)(((\w{0,15})))?))(:.\S.*)';
error_msg="Aborting commit. Your commit message format is invalid, please check the references."
commit_message="$1";

if ! grep -iqE "$commit_regex" <<<"${commit_message}"; then
echo "$error_msg" >&2
exit 1
fi

if [ "$branch" = "master" ]; then
echo "You can't commit directly to master branch"
exit 1
fi

if [ "$branch" = "develop" ]; then
echo "You can't commit directly to develop branch"
exit 1
fi

Captura de Pantalla 2019-09-25 a la(s) 10 05 57

You can test this regex expression here

Hi,

Can you tell me in which linux file this statement should be added and an example of how to use it,

Thank you

@jpcmf

This comment has been minimized.

Copy link

jpcmf commented Jan 21, 2020

I will try, thank you :)

@joshbuchea

This comment has been minimized.

Copy link
Owner Author

joshbuchea commented Jan 21, 2020

Confession: I rarely follow these commit conventions.

It's not for a lack of trying though! In theory, these conventions are excellent and I would love to see high quality commit messages like these in every codebase. For me personally, I find determining the type of a commit requires too much mental overhead. That and most of the projects I work on these days merge-squash branches, so only one commit message lives on in the codebase.

@dagadbm

This comment has been minimized.

Copy link

dagadbm commented Feb 19, 2020

can you also mention the scope here?

@jD4rk

This comment has been minimized.

Copy link

jD4rk commented Feb 29, 2020

scope usually target a specific architecture component of the project.

For example, in a MVP project when you change or refactor something about only the model can you write something like:

Add(model): new field phone number in the user model.....

@julessaysrawr

This comment has been minimized.

Copy link

julessaysrawr commented Mar 4, 2020

@joshbuchea I created an alias in my shell profile to make it easier to use commit types. I can run a quick command before I commit with a reminder of what the options are.

In my dotfiles repo, i have a commit types file which is

feat - A new feature
fix - A bug fix
docs - Documentation only changes
style - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor - A code change that neither fixes a bug nor adds a feature
perf - A code change that improves performance
test - Adding missing tests or correcting existing tests
build - Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci - Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
chore - Other changes that don't modify src or test files
revert - Reverts a previous commit

and in my shell profile i have the following aliases

alias commit-types='cat ~/dotfiles/commit-types'
alias ct='cat ~/dotfiles/commit-types'

The aliases will just print out the contents of the commit types file into my terminal.

So when I have my files staged and ready to commit, i just run ct and it will list the commit types out for me. It make me use them all the time if they are at the tips of my fingers. 🎉

@padamstx

This comment has been minimized.

Copy link

padamstx commented Mar 9, 2020

Is anyone aware of a commit message validation step that could be configured as a required PR check in github? I'd like to enforce the angular commit message conventions in a few projects.

@joshbuchea

This comment has been minimized.

Copy link
Owner Author

joshbuchea commented Mar 11, 2020

@julessaysrawr that's super handy! Thank you for sharing 🙌

@jD4rk

This comment has been minimized.

Copy link

jD4rk commented Mar 12, 2020

well
a proper solution that ensure to never forgot about tag (or anything else you and your team like)
is to create a template file with any name you want, and add on it lines below:

# TAG CAN BE
#       Add             Create a capability e.g. feature, test, dependency.
#       Cut             Remove a capability e.g. feature, test, dependency.
#       Fix             Fix an issue e.g. bug, typo, accident, misstatement.
#       Start           Begin doing something; e.g. create a feature flag.
#       Stop            End doing something; e.g. remove a feature flag.
#       Bump            Increase the version of something e.g. dependency.
#       Test            Add or refector anything regard test, e.g add a new testCases.
#       Make            Change the build process, or tooling, or infra.
#       Refactor        A code change that MUST be just a refactoring.
#       Reformat        Refactor of formatting, e.g. omit whitespace.
#       Optimize        Refactor of performance, e.g. speed up code.
#       Document        Refactor of documentation, e.g. help files.
#       License         Edits regarding licensing; no production code change.
#       Revert          Change back to the previous commit

Then just set globally on your git to use above file as template for all your commit with the command:

git config --global commit.template ~/yourfilename

And voilà....any time you send commit message on your repo git will pick up that file and you will never forgot about your commit types!

Note you can leave all those line when you finish to add your commit message and save the file to proceed with the commit due the fact that all lines with comment (# at the beginning) will not write in the real commit message

@Nandtrocity

This comment has been minimized.

Copy link

Nandtrocity commented Mar 18, 2020

awesome, thank you!

@adrianojdesouza

This comment has been minimized.

Copy link

adrianojdesouza commented Mar 23, 2020

Very useful, thanks a lot.

@GoldenMaximo

This comment has been minimized.

Copy link

GoldenMaximo commented Mar 24, 2020

Super simple and easy to understand. Saves a lot of trouble when reading commit messages!

@seunggabi

This comment has been minimized.

Copy link

seunggabi commented Apr 1, 2020

genius!

@yzk23

This comment has been minimized.

Copy link

yzk23 commented Apr 2, 2020

Thanks!!

@LOG-INFO

This comment has been minimized.

Copy link

LOG-INFO commented Apr 3, 2020

Thanks :)

@Rodrirokr

This comment has been minimized.

Copy link

Rodrirokr commented Apr 7, 2020

Having a dumb question, a commit with .gitignore changes, wich type would have?

@tim-phillips

This comment has been minimized.

Copy link

tim-phillips commented Apr 9, 2020

@Rodrirokr, that would fall under chore.

@CristoferPortela

This comment has been minimized.

Copy link

CristoferPortela commented Apr 18, 2020

very useful man, thanks, I have a question about feat and refactor, if I add a new function that will just return a json, should I use feat or refactor?

@rendertom

This comment has been minimized.

Copy link

rendertom commented Apr 21, 2020

If you add something new to the codebase, then it's a feature.
It cannot be refactoring since it collides with the refactoring principle (taken from Wikipedia): Code refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior.

@GiovannyCano

This comment has been minimized.

Copy link

GiovannyCano commented May 7, 2020

Thanks

@abbasogaji

This comment has been minimized.

Copy link

abbasogaji commented May 22, 2020

hey guys quick question, doesn't style() and refactor() feel very similar? whats the major difference between style() and refactor()?

@curtisbelt

This comment has been minimized.

Copy link

curtisbelt commented May 22, 2020

@abbasogaji

hey guys quick question, doesn't style() and refactor() feel very similar? whats the major difference between style() and refactor()?

For style , think about if you run an auto format tool on a whole project (like prettier.js) - all the changes are "stylistic" - fixing code spacing, consistency with tab or space usage, etc. I'd also consider some syntax changes to count as stylistic - for instance eslint/prettier.js can enforce using ES6 features in javascript - if they don't affect behavior then it's stylistic IMO. The line can get a little blurry here, this is true.

If I'm doing a refactor, I'm not focusing on cleaning up the code "style", but rather I'm cleaning up the logic itself to be easier to understand. So this would be like if I rewrite a function completely.

Hope that helps!

@abbasogaji

This comment has been minimized.

Copy link

abbasogaji commented May 22, 2020

@curtisbelt thanks

@seunggabi

This comment has been minimized.

Copy link

seunggabi commented May 30, 2020

To. @joshbuchea
I write a semantic-branch-names.md.
it is very similar with semantic-commit-messages.md.

That's why I think that branch name is too important.
I hope it helps.

https://gist.github.com/seunggabi/87f8c722d35cd07deb3f649d45a31082

@innokenty

This comment has been minimized.

Copy link

innokenty commented Jun 4, 2020

I think it's a great structure and I'm using it myself. Some things I wanted to point out/ask though:

  1. It is a very common practice to include ticket numbers in the commit messages. IF you wanna do it together with semantic commits – then my suggestion would be to include the ticket number at the very beginning. It is true that it usually is not a very useful information for developers, so you could also include it at the very end in brackets or so, or in the commit body.

    However putting the number at the beginning has one big advantage which is: ticket numbers are always the same length! (and usually the same prefix) So if you follow my suggestion – you effectively create another column in your git log, preceding the commit message, and it's really easy to read or skip when reading. Like that:

    YOURMUM-117 - feat: never gonna give you up
    YOURMUM-169 - fix: never gonna let you down
    YOURMUM-666 - refactor: never gonna run around and desert you
    
  2. This is more of a question. I'm struggling to decide which type I should use when I change logging only. Like add extra log lines, reword english sentences or fix some missing parameters.

    Is it a feature? It's not affecting the users or the flow of the program. Is it a fix? Nothing was broken, and it's working as before. Is it a factoring? Not really, cuz it does affect the system behaviour, while refactorings are often just code style and such.

@curtisbelt

This comment has been minimized.

Copy link

curtisbelt commented Jun 4, 2020

@innokenty

  1. I like that a lot, at work we use the format JIRA-0000: Never gonna give you up (we don't use semantic commits). I actually find it useful even as a developer, especially when working with multiple developers in the same codebase - it's been useful to be able to read up on the original ticket to follow their footsteps. Can also catch non-programmatic errors this way since you can confirm "their code does X but their ticket said to do Y".

  2. I use semantic messages in personal projects, and know exactly what you mean. Many times I've tried to google what "type" others would use for a particular situation, but it's hard to get that specific answer. The answer is probably to come up with your own set of types to fit your needs. For your case, maybe a new log or debug type is necessary.

    Otherwise I think a lot of people use chore as a fallback. Angular actually removed chore from their official commit message types because it was overused in this way... but conventional commits kept it, probably because it helps give people an option in your situation.

@wohlford

This comment has been minimized.

Copy link

wohlford commented Jun 7, 2020

So when I have my files staged and ready to commit, i just run ct and it will list the commit types out for me. It make me use them all the time if they are at the tips of my fingers. 🎉

@julessaysrawr, I love this. Thank you.

Mine below:

^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, or test

feat: new feature for the user, not a new feature for build script
fix: a bug fix
docs: changes to the documentation only
style: formatting, white-space, etc; no production code change
refactor: code change that does not fix a bug or add a feature, eg. renaming a variable
perf: code change that improves performance
test: adding missing tests, refactoring tests; no production code change
build: change that affects the build system or external dependencies (example scopes: gulp, npm)
ci: change to the CI configuration files and scripts
chore: change that does not modify src or test files
revert: reverts a previous commit```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.