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 YelemyahM commented Oct 15, 2018

Thanks it's very useful

@codebender828

This comment has been minimized.

Copy link

@codebender828 codebender828 commented Dec 7, 2018

Thanks. Good stuff

@adnanhz

This comment has been minimized.

Copy link

@adnanhz adnanhz commented Jan 9, 2019

Thanks

@lwwcas

This comment has been minimized.

Copy link

@lwwcas lwwcas commented Jan 15, 2019

Starting today, I'll start using it, thanks

@kevinjalbert

This comment has been minimized.

Copy link

@kevinjalbert 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 tobyokeke commented Mar 15, 2019

thanks.

@keymusicman

This comment has been minimized.

Copy link

@keymusicman 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 YourSouLi5Mine commented Apr 5, 2019

@keymusicman you can use wip for work in progress

@marinoguerieri

This comment has been minimized.

Copy link

@marinoguerieri marinoguerieri commented Aug 6, 2019

Thanks

@HoracioEspinosa

This comment has been minimized.

Copy link

@HoracioEspinosa 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 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 rlocatelli9 commented Dec 19, 2019

thanks bro

@avidal2433

This comment has been minimized.

Copy link

@avidal2433 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 jpcmf commented Jan 21, 2020

I will try, thank you :)

@joshbuchea

This comment has been minimized.

Copy link
Owner Author

@joshbuchea 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 dagadbm commented Feb 19, 2020

can you also mention the scope here?

@jD4rk

This comment has been minimized.

Copy link

@jD4rk 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 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 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 joshbuchea commented Mar 11, 2020

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

@jD4rk

This comment has been minimized.

Copy link

@jD4rk 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 Nandtrocity commented Mar 18, 2020

awesome, thank you!

@adrianojdesouza

This comment has been minimized.

Copy link

@adrianojdesouza adrianojdesouza commented Mar 23, 2020

Very useful, thanks a lot.

@GoldenMaximo

This comment has been minimized.

Copy link

@GoldenMaximo 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 seunggabi commented Apr 1, 2020

genius!

@yzk23

This comment has been minimized.

Copy link

@yzk23 yzk23 commented Apr 2, 2020

Thanks!!

@LOG-INFO

This comment has been minimized.

Copy link

@LOG-INFO LOG-INFO commented Apr 3, 2020

Thanks :)

@Rodrirokr

This comment has been minimized.

Copy link

@Rodrirokr 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 tim-phillips commented Apr 9, 2020

@Rodrirokr, that would fall under chore.

@CristoferPortela

This comment has been minimized.

Copy link

@CristoferPortela 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 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.

@abbasogaji

This comment has been minimized.

Copy link

@abbasogaji 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 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 abbasogaji commented May 22, 2020

@curtisbelt thanks

@seunggabi

This comment has been minimized.

Copy link

@seunggabi 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 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 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 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```
@jgomer2001

This comment has been minimized.

Copy link

@jgomer2001 jgomer2001 commented Sep 10, 2020

make you a better programmer

How do commit messages make you a better programmer? Programming is coding in a language. This won't make you write better code at all.

@jpcmf

This comment has been minimized.

Copy link

@jpcmf jpcmf commented Sep 10, 2020

make you a better programmer

How do commit messages make you a better programmer? Programming is coding in a language. This won't make you write better code at all.

Better programmer is not about only code, mate. Think about :)

@oicitrapdraz

This comment has been minimized.

Copy link

@oicitrapdraz oicitrapdraz commented Sep 11, 2020

How do commit messages make you a better programmer? Programming is coding in a language. This won't make you write better code at all.

Use good conventions in a tool used for almost every programmer? Nah, that doesn't matter.

Now do you understand that you sound like an idiot?

@dagadbm

This comment has been minimized.

Copy link

@dagadbm dagadbm commented Sep 11, 2020

@jgomer2001

This comment has been minimized.

Copy link

@jgomer2001 jgomer2001 commented Sep 11, 2020

Github no es para insultar @oicitrapdraz, si eso quiere, use twitter

@oicitrapdraz

This comment has been minimized.

Copy link

@oicitrapdraz oicitrapdraz commented Sep 14, 2020

Github no es para insultar @oicitrapdraz, si eso quiere, use twitter

Bueno, ahi te lo pongo sin insulto @jgomer2001

Use good conventions in a tool used for almost every programmer? Nah, that doesn't matter.

That's not very smart from you...

@joshbuchea

This comment has been minimized.

Copy link
Owner Author

@joshbuchea joshbuchea commented Sep 15, 2020

Please keep discussion civil and do not make personal remarks about individuals or I'll be forced to remove comments and/or block any troublemakers 🙏

Have a great day :)

@Segmentational

This comment has been minimized.

Copy link

@Segmentational Segmentational commented Sep 20, 2020

These commit practices also allow for some really powerful automation downstream; take for example:

Pattern Description Alias(es)
Revert, U Reverts a previous commit [U]ndo, Reversion, Reverted, Mistake
Fix, B Work towards bug-related code [B]ugfix, Bug-Fix, Hot-Fix, Hotfix
[F]eature, F Creation of a capability: implementation of a dependency, test, functionality Add, Added, Addition, Implementation Implemented
Bump, V Increase version; i.e. updating a dependency [V]ersion, Release
[T]est, T Additions or refactoring of anything test-related Unit, Interoperability, Stage
[B]uild, B Force a pipeline trigger Not Applicable
No-Build, X Force no pipeline trigger Not Applicable
C[I], I Changes to CI configuration files and scripts Under Further Consideration
[R]efactor,R A code change that neither fixes a bug nor adds a feature Refactoring
[S]tyle, S Deprivation of Refactor - white space, semi-colons, etc Styling, Styles, Markup
[O]ptimize,O Deprivation of Refactor - runtime, build optimizations Optimizing, Optimization
[D]ocument,D Deprivation of Refactor - code documentation Documentation, README, Information, ILC, In-Line-Comment, In-Line-Comments, Clarification

-- then regular expressions could use these patterns and maybe flags (e.g. -U for Revert) + aliases in a pipeline, bash script, web-hook, container, etc. to further extend version control.

@oicitrapdraz, I do understand where you might be coming from. However, because it doesn't necessarily "[...] make you a better programmer" at a surface level, employing applications that use some form of version control naming convention(s) (i.e commit messages, branch names, etc.) will not only make you a better programmer, but potentially your entire development team. (:

For those curious, here's a personal implementation (GitLab CICD).

*Updated Implementation Example Hyperlink.

@gomorizsolt

This comment has been minimized.

Copy link

@gomorizsolt gomorizsolt commented Oct 1, 2020

Thanks, awesome!

@cauezito

This comment has been minimized.

Copy link

@cauezito cauezito commented Oct 26, 2020

Thanks ;)

@dariusz-wozniak

This comment has been minimized.

Copy link

@dariusz-wozniak dariusz-wozniak commented Nov 12, 2020

Thanks :)

Forked with a few additions:

  • bump: (version update)
  • ci: (changes to the build config)
  • localize: (translations update)
  • perf: (performance improvements)
@jackdalton2

This comment has been minimized.

Copy link

@jackdalton2 jackdalton2 commented Nov 21, 2020

Thanks! @Segmentational

@shanezhiu

This comment has been minimized.

Copy link

@shanezhiu shanezhiu commented Dec 16, 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
the .git/hooks directory under you project

@nhevia

This comment has been minimized.

Copy link

@nhevia nhevia commented Jan 17, 2021

Count commits types support.

Example:
image

@heithemmoumni

This comment has been minimized.

Copy link

@heithemmoumni heithemmoumni commented Jan 22, 2021

       /‾‾‾‾‾‾‾‾
  😼  <  Meow! Please use semantic commit messages
       \________

  <type>[<scope>]: <short summary>
     │      │             │
     │      │             └─> Summary in present tense. Not capitalized. No period at the end. 
     │      │
     │      └─> Scope: common|compiler|authentication|core|
     │                                                                                          
     └─> Type: chore, docs, feat, fix, refactor, style, or test.

https://github.com/heithemmoumni/commit.meow/blob/main/README.md

@remy727

This comment has been minimized.

Copy link

@remy727 remy727 commented Jan 29, 2021

Amazing! 👍

@brickzzhang

This comment has been minimized.

Copy link

@brickzzhang brickzzhang commented Feb 8, 2021

Useful 👍

@seunggabi

This comment has been minimized.

Copy link

@seunggabi seunggabi commented Feb 16, 2021

       /‾‾‾‾‾‾‾‾
  😼  <  Meow! Please use semantic commit messages
       \________

  <type>[<scope>]: <short summary>
     │      │             │
     │      │             └─> Summary in present tense. Not capitalized. No period at the end. 
     │      │
     │      └─> Scope: common|compiler|authentication|core|
     │                                                                                          
     └─> Type: chore, docs, feat, fix, refactor, style, or test.

https://github.com/heithemmoumni/commit.meow/blob/main/README.md


I recommend to add issue# !!

<type>[<scope>](<issue#>): <short summary>
                     │                                                                                          
                     └─> issue#: issue & pr number
@liumenghua

This comment has been minimized.

Copy link

@liumenghua liumenghua commented Mar 3, 2021

very useful!thanks a lot!

@chojnicki

This comment has been minimized.

Copy link

@chojnicki chojnicki commented Mar 8, 2021

@lwwcas

Starting today, I'll start using it, thanks

I checked your repositories - LIAR! :D

But seriously, this convention sounds great but it's rarely used. Even author of this gist does not using it :D Will see how long it will be in my case, and it is worth hassle.

@xuyxu

This comment has been minimized.

Copy link

@xuyxu xuyxu commented Mar 23, 2021

Thanks @joshbuchea, really helpful.

@hyfydistro

This comment has been minimized.

Copy link

@hyfydistro hyfydistro commented Mar 28, 2021

I am not sure when to use <scope> or when I'm just building stuff onto my page (i.e. still in production mode).

@PMExtra

This comment has been minimized.

Copy link

@PMExtra PMExtra commented Mar 29, 2021

Which scope should I choose when I updated a dependency that doesn't fix any known issue, just a general update.

@shivaylamba

This comment has been minimized.

Copy link

@shivaylamba shivaylamba commented Apr 11, 2021

@JohnnyWalkerDesign

This comment has been minimized.

Copy link

@JohnnyWalkerDesign JohnnyWalkerDesign commented Apr 19, 2021

You should add a few more examples. I've seen people think that they're supposed to write <feat>: add new feature instead of feat: add new feature.

@JohnnyWalkerDesign

This comment has been minimized.

Copy link

@JohnnyWalkerDesign JohnnyWalkerDesign commented Apr 19, 2021

Tweaked:

       /‾‾‾‾‾‾‾‾
  😼  <  Meow! Please use semantic commit messages
       \________

  <type>[<scope>](issue #): <short summary>
     │      │        |             │
     |      |        |             └─> Summary in present tense. Not capitalized. No period at the end. 
     |      |        |  
     │      │        └─> Issue # (optional): Issue number if related to bug database.           
     │      │
     │      └─> Scope (optional): eg. common, compiler, authentication, core
     │                                                                                          
     └─> Type: chore, docs, feat, fix, refactor, style, or test.
@vishant007

This comment has been minimized.

Copy link

@vishant007 vishant007 commented Apr 28, 2021

too helpfull!!

@qianxi0410

This comment has been minimized.

Copy link

@qianxi0410 qianxi0410 commented May 8, 2021

Thx xD

@yiblet

This comment has been minimized.

Copy link

@yiblet yiblet commented May 13, 2021

Say you're deleting a feature without replacing it with something better. What would you call that? a chore? a feat?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment