Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Conventional Commit Messages

Conventional Commit Messages

See how a minor change to your commit message style can make a difference. Examples

Have a look at CLI util git-conventional-commits to ensure this conventions and generate changelogs

Commit Formats

Default

<type>(<optional scope>): <subject>
empty separator line
<optional body>
empty separator line
<optional footer>

Merge

Merge branch '<branch name>'

Follows default git merge message

Types

  • API relevant changes
    • feat Commits, that adds a new feature
    • fix Commits, that fixes a bug
  • refactor Commits, that rewrite/restructure your code, however does not change any behaviour
    • perf Commits are special refactor commits, that improve performance
  • style Commits, that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
  • test Commits, that add missing tests or correcting existing tests
  • docs Commits, that affect documentation only
  • build Commits, that affect build components like build tool, ci pipeline, dependencies, project version, ...
  • ops Commits, that affect operational components like infrastructure, deployment, backup, recovery, ...
  • chore Miscellaneous commits e.g. modifying .gitignore

Scopes

The scope provides additional contextual information.

  • Is an optional part of the format
  • Allowed Scopes depends on the specific project
  • Don't use issue identifiers as scopes

Subject

The subject contains a succinct description of the change.

  • Is a mandatory part of the format
  • Use the imperative, present tense: "change" not "changed" nor "changes"
    • Think of This commit will <subject>
  • Don't capitalize the first letter
  • No dot (.) at the end

Body

The body should include the motivation for the change and contrast this with previous behavior.

  • Is an optional part of the format
  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • This is the place to mention issue identifiers and their relations

Footer

The footer should contain any information about Breaking Changes and is also the place to reference Issues that this commit refers to.

  • Is an optional part of the format
  • optionally reference an issue by its id.
  • Breaking Changes should start with the word BREAKING CHANGES: followed by space or two newlines. The rest of the commit message is then used for this.

Examples

  • feat(shopping cart): add the amazing button
    
  • feat: remove ticket list endpoint
    
    refers to JIRA-1337
    BREAKING CHANGES: ticket enpoints no longer supports list all entites.
    
  • fix: add missing parameter to service call
    
    The error occurred because of <reasons>.
    
  • build(release): bump version to 1.0.0
    
  • build: update dependencies
    
  • refactor: implement calculation method as recursion
    
  • style: remove empty line
    

Git Hook Scripts to ensure commit message header format

commit-msg Hook (local)

  • create following file in your local repository folder.git-hooks/commit-msg
    #!/usr/bin/env sh
    
    commit_message="$1"
    # exit with a non zero exit code incase of an invalid commit message
    
    # use git-conventional-commits, see https://github.com/qoomon/git-conventional-commits
    git-conventional-commits commit-msg-hook "$commit_message"
    
    # or verify $commit_message with your own tooling
    # ...
    
  • make .git-hooks/commit-msg executable (unix: chmod +x '.git-hooks/commit-msg')
  • set git hook directory to .githooks git config core.hooksPath '.git-hooks'
  • commit .git-hooks directory if you want to share them with your team, they only need to call the git config command once after cloning the repository

pre-receive Hook (server side)

  • create following file in your repository folder .git/hooks/pre-receive
    #!/usr/bin/env sh
    
    # Pre-receive hook that will block commits with messges that do not follow regex rule
    
    commit_msg_type_regex='feat|fix|refactor|style|test|docs|build'
    commit_msg_scope_regex='.{1,20}'
    commit_msg_subject_regex='.{1,100}'
    commit_msg_regex="^(${commit_msg_type_regex})(\(${commit_msg_scope_regex}\))?: (${commit_msg_subject_regex})\$"
    merge_msg_regex="^Merge branch '.+'\$"
    
    zero_commit="0000000000000000000000000000000000000000"
    
    # Do not traverse over commits that are already in the repository
    excludeExisting="--not --all"
    
    error=""
    while read oldrev newrev refname; do
      # branch or tag get deleted
      if [ "$newrev" = "$zero_commit" ]; then
        continue
      fi
    
      # Check for new branch or tag
      if [ "$oldrev" = "$zero_commit" ]; then
        rev_span=`git rev-list $newrev $excludeExisting`
      else
        rev_span=`git rev-list $oldrev..$newrev $excludeExisting`
      fi
    
      for commit in $rev_span; do
        commit_msg_header=$(git show -s --format=%s $commit)
        if ! [[ "$commit_msg_header" =~ (${commit_msg_regex})|(${merge_msg_regex}) ]]; then
          echo "$commit" >&2
          echo "ERROR: Invalid commit message format" >&2
          echo "$commit_msg_header" >&2
          error="true"
        fi
      done
    done
    
    if [ -n "$error" ]; then
      exit 1
    fi
  • make .git/hooks/pre-receive executable (unix: chmod +x '.git/hooks/pre-receive')

References


@JimmyMultani
Copy link

JimmyMultani commented Apr 17, 2020

This was helpful. Thank you for sharing!

@segun-luwi
Copy link

segun-luwi commented Sep 30, 2020

Great work, keep doing the good work!

@CupCakeR
Copy link

CupCakeR commented Dec 30, 2020

If you are on Windows and are also struggling to set it up locally, don't forget to try the fix mentioned in the instructions here.

@ujjwalstha
Copy link

ujjwalstha commented Aug 6, 2021

Thank you for the share.
But I have one question. What would be a suitable conventional commit message for deleted files?

@qoomon
Copy link
Author

qoomon commented Aug 6, 2021

@ujjwalstha depends on the file :-) In general I would say you should think of the behaviour that change by deleting your file, if it changes ops behaviour ex. ops: ${new behaviour} if it removes a feature ex. feature: remove ${feature} and so on. If it does not change behaviour it should be refactor: .... If non of that really fits as a last resort take chore: ...

@dmutoni
Copy link

dmutoni commented Nov 22, 2021

thanks for sharing

@iamaakashbasnet
Copy link

iamaakashbasnet commented Mar 26, 2022

Thanks for sharing! :)

@marcothz
Copy link

marcothz commented Apr 6, 2022

Hey @qoomon,

I've just made a tiny fix and made it available here conventional_commit_messages.md.

💙

@qoomon
Copy link
Author

qoomon commented Apr 7, 2022

@marcothz thanks a lot I'll merge it

@jmrafael
Copy link

jmrafael commented Jun 21, 2022

Wonderfull 😁👏

@gutisalex
Copy link

gutisalex commented Jun 30, 2022

using gitlab, the MR always puts its own commit message smth like Merge branch 'feature xyz' into 'develop'. I found where I can change the template under general - settings... but I wonder what would be the type of merge and squas commit messages?

@qoomon
Copy link
Author

qoomon commented Jun 30, 2022

In my opinion there are 2 two way to handle merge messages

  • #1 allow default merge messages e.g. https://github.com/qoomon/git-conventional-commits will treat them as a merge commit
  • #2 decide whether it is a fix, a feat or something else and try to sum up what has happened on the branch and create a new commit message.

I highly recommend the first way if your merge contains more than one type of commits

@andreygio
Copy link

andreygio commented Aug 16, 2022

Hi @qoomon, I am getting this error: No names found, cannot describe anything when I executed version command in a new repository what should I do to get my first changelog file when the repository is new and have no tags?

@qoomon
Copy link
Author

qoomon commented Aug 16, 2022

@andreygio for now you need to tag the initial commit with v0.0.0 or whatever your version pattern looks like. I'll consider to fix that in the cli by having a default version of 0.0.0 in that case.

@qoomon
Copy link
Author

qoomon commented Aug 17, 2022

@greeneley
Copy link

greeneley commented Sep 4, 2022

Great, thanks a lot

@howsmyanimeprofilepicture

Thank you for the nice resource !! It is really helpful to me ... 💕💕💕💕💕

@qoomon
Copy link
Author

qoomon commented Sep 17, 2022

@howsmyanimeprofilepicture glad to hear that.

@BoboTheBarbar
Copy link

BoboTheBarbar commented Oct 26, 2022

Thanks a lot, that is really helpful 👍
One question though: is there a reason we prefer the imperative, present tense in subject and body?

@qoomon
Copy link
Author

qoomon commented Oct 26, 2022

@BoboTheBarbar this is caused by the idea that a commit message should always complete the sentence This commit will... or This commit will <subject>.

@BoboTheBarbar
Copy link

BoboTheBarbar commented Oct 26, 2022

@qoomon this, sir, just made writing my commit messages much more meaningful and rewarding for me. Thanks for that :)

@chrop01
Copy link

chrop01 commented Nov 22, 2022

How to commit new comments? Is this "style:"?

@qoomon
Copy link
Author

qoomon commented Nov 22, 2022

I would say docs

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