qoomon/conventional-commits-cheatsheet.md

Last active June 8, 2025 18:28

Star (3,258) You must be signed in to star a gist
Fork (519) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13.js"></script>
Save qoomon/5dfcdf8eec66a051ecd85625518cfd13 to your computer and use it in GitHub Desktop.

Download ZIP

Conventional Commits Cheatsheet

Raw

conventional-commits-cheatsheet.md

Conventional Commit Messages

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

git commit \
  -m"<type>(<optional scope>): <description>" \
  -m"<optional body>" \
  -m"<optional footer>"

Tip

Take a look at git-conventional-commits , a CLI util to ensure these conventions, determine version and generate changelogs

Commit Message Formats

General Commit

<type>(<optional scope>): <description>
_{empty separator line}
<optional body>
_{empty separator line}
<optional footer>

Merge Commit

Merge branch '<branch name>'

^{Follows default git merge message}

Revert Commit

Revert "<reverted commit subject line>"

^{Follows default git revert message}

Initial Commit

chore: init

Types

Changes relevant to the API or UI:
- feat Commits that add, adjust or remove a new feature to the API or UI
- fix Commits that fix an API or UI bug of a preceded feat commit
refactor Commits that rewrite or restructure code without altering API or UI behavior
- perf Commits are special type of refactor commits that specifically improve performance
style Commits that address code style (e.g., white-space, formatting, missing semi-colons) and do not affect application behavior
test Commits that add missing tests or correct existing ones
docs Commits that exclusively affect documentation
build Commits that affect build-related components such as build tools, dependencies, project version, CI/CD pipelines, ...
ops Commits affecting operational aspects like infrastructure, deployment processes, backup, or recovery procedures.
ops Commits that affect operational components like infrastructure, deployment, backup, recovery procedures, ...
chore Miscellaneous commits e.g. modifying .gitignore, ...

Scopes

The scope provides additional contextual information.

The scope is an optional part
Allowed scopes vary and are typically defined by the specific project
Do not use issue identifiers as scopes

Breaking Changes Indicator

Breaking changes should be indicated by an ! before the : in the subject line e.g. feat(api)!: remove status endpoint
Breaking changes must be described in the commit footer section

Description

The description contains a concise description of the change.

The description is a mandatory part
Use the imperative, present tense: "change" not "changed" nor "changes"
- Think of This commit will... or This commit should...
Do not capitalize the first letter
Do not end the description with a period (.)

Body

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

The body is an optional part
Use the imperative, present tense: "change" not "changed" nor "changes"

Footer

The footer should contain issue references and informations about Breaking Changes

The footer is an optional part, except if the commit introduce breaking changes
Optionally reference issue identifiers (e.g., Closes #123, Fixes JIRA-456)
Breaking Changes should start with the word BREAKING CHANGE: followed by space or two newlines. The rest of the commit message is then used for this.

Versioning

If your next release contains commit with...
- Breaking Changes incremented the major version
- API relevant changes (feat or fix) incremented the minor version
Else increment the patch version

Examples

feat: add email notifications on new direct messages

feat(shopping cart): add the amazing button

feat!: remove ticket list endpoint

refers to JIRA-1337

BREAKING CHANGE: ticket endpoints no longer supports list all entities.

fix(shopping-cart): prevent order an empty shopping cart

fix(api): fix wrong calculation of request body checksum

fix: add missing parameter to service call

The error occurred due to <reasons>.

perf: decrease memory footprint for determine unique visitors by using HyperLogLog

```
build: update dependencies
```
```
build(release): bump version to 1.0.0
```

refactor: implement fibonacci number calculation as recursion

```
style: remove empty line
```

Git Hook Scripts to ensure commit message header format

Click to expand

commit-msg Hook (local)

Create a commit-msg hook using git-conventional-commits cli

pre-receive Hook (server side)

create following file in your repository folder .git/hooks/pre-receive

#!/usr/bin/env bash

# Pre-receive hook that will block commits with messages 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_description_regex='.{1,100}'
commit_msg_regex="^(${commit_msg_type_regex})(\(${commit_msg_scope_regex}\))?: (${commit_msg_description_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

Author

qoomon commented Feb 27, 2025

the enhancement is used for improvement changes smaller in scope than feature. so say, the existing behaviour is improved in some sense, or some additional case is handled, or 1-4 liner tweaks etc.

I strongly recommend to use feator fix if it changes the API even just a tiny bit. That is the most important information for a commit.

the refactor is just way toooo long, even when compared with rest all other types.
so, i use refac from quite some time and it works much better for readability.
read more here: cyb3rko/pincredible#27

I would recommend to use refactor because using abbreviation always lead to less readability afterwards. Saving 4 characters will not have a measurable impact on development. However feel free to use another convention in your projects. The only relevant types are fix and feat I know this is an abbreviation, I don't like it however it's part of the https://www.conventionalcommits.org/en/v1.0.0/ definition and I like to stick to standards.

on continued note of refactoring, there's also code restructuring or rewrite (say, for merge commits)... but in my limited anecdotes, it is very messy.

I don't see any reason or additional value in splitting refactoring up in to more granular refactoring types. This will only make it mor difficult to choose between all the types.

some people dedicatedly use ci type separate from build.

If it adds value for your project go for it. In my experience ci can be better described as ops related commit if you do a deployment relevant change or test if you add something to improve testing before deploying or build if your commit the build of your artifacts.

goyalyashpal commented Feb 27, 2025 •

edited

Loading

thanks a lot for sharing detailed thoughts.

i agree with you on not splitting refac further.
as for the enh, there are several times when there is no API. like in:
- creating some static website (like profile readmes, or blogs, etc), or
- producing some PDF document (like book, manual, etc). or
- package metadatas / configs (like scoop for windows, pkg files for arch, or nixpkgs / flakes for nixos)
in all these cases, enhance helps a lot.
i appreciate standards, but in this case, i like to stick to 52 character limit in the commit title more, and even if you ignore the readability improvements, those 3 characters really make or break things at times.
thanks a lot for detailing on ci too. i haven't had much experience with build tools, will keep in mind in future.

Author

qoomon commented Feb 27, 2025

as for the enh, there are several times when there is no API. like in:
creating some static website (like profile readmes, or blogs, etc), or

readme would be docs, a new blog post would be a new feat if you add static content to your repo

producing some PDF document (like book, manual, etc). or

most likely docs commit as well

package metadatas / configs (like scoop for windows, pkg files for arch, or nixpkgs / flakes for nixos)

these would be ops commits

goyalyashpal commented Feb 27, 2025 •

edited

Loading

most likely docs commit as well

not if the whole repo is dedicated to docs lol 😆

yes, readme comes under docs for normal repos. but in case of profile repos, the readme is the main show itself.

Author

qoomon commented Feb 27, 2025 •

edited

Loading

but in case of profile repos, the readme is the main show itself.

then its a feat commit. it depends on what is your interface of your application (API/UI)

barraIhsan commented Mar 9, 2025

What do you guys think about adding/modifying a comments to clarify the code fall into?
Is it docs or style

Author

qoomon commented Mar 9, 2025

@barraIhsan what's not clear about the current comments

docs Commits, that affect documentation only
style Commits, that do not affect the meaning (white-space, formatting, missing semi-colons, etc)

Do you have suggestions to improve the comments?

barraIhsan commented Mar 9, 2025 •

edited

Loading

no, I meant I was asking if I edited a comments in my codebase, what commit type it should fall into?
For example

+ // This function will add two numbers
fn add(x: i32, y: i32) {
  x+y
}

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

Oh also, isn't it supposed to be BREAKING CHANGE: without s?

barraIhsan commented Mar 9, 2025

and, when we're removing something like remove pages, remove unused functions, replace a plugin with another one.
We use feat for that right? I've been using chore this whole time. I interpret it as the wildcard type.

Author

qoomon commented Mar 9, 2025

@barraIhsan

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

I would chose docs as well for these changes.

Author

qoomon commented Mar 9, 2025

@barraIhsan

Oh also, isn't it supposed to be BREAKING CHANGE: without s?

yes you are right I'll fix that or add singular wording as well i think both singular and plural should be valid

barraIhsan commented Mar 9, 2025

@barraIhsan

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

I would chose docs as well for these changes.

ahh okay then. Thanks for clarifying that out. I've been using it all wrong this whole time

Author

qoomon commented Mar 9, 2025

@barraIhsan

and, when we're removing something like remove pages,

if that results in an change for the user it should be a feat otherwise it's probably refactor

remove unused functions,

probably it's a refactor commit, unless it changes the api of your project e.g. you project is an library and the function was exposed to lib users then it would be feat

replace a plugin with another one.

probably it's a refactor commit, unless it also change the the ui or api of your project

I've been using chore this whole time. I interpret it as the wildcard type.

chore should definitely not be used as a wildcard type or fallback type

barraIhsan commented Mar 9, 2025

ahh okay! Thanks for the clarification!

muzaffaar commented Apr 8, 2025

Amazing!

Author

qoomon commented Apr 10, 2025

🙏thanks :-)

malihehmoradi commented Apr 22, 2025 •

edited

Loading

Is it appropriate to use chore when we're only updating the version of a dependency?

Author

qoomon commented Apr 22, 2025

@malihehmoradi IMHO it should be build or even build(deps): ... because build indicates changes in the build process that includes changes to dependencies

Author

qoomon commented Apr 24, 2025

@flip12322 💚

hacker-hackman commented May 8, 2025 •

edited

Loading

What type should be used when we've updated our app's repository to incorporate changes from the upstream repository on which our app is based?

I've named the commit like this:
chore: sync codebase with upstream repository changes

Author

qoomon commented May 8, 2025

@hacker-hackman thats a tricky one. If its a merge just keep it a merge commit. If it is a commit without history, then it depends what the changes are, in other words could be any commit type. chore is probably not a good fit because it gives the impression of an safe commit without the risk of breaking changes or new features.

Author

qoomon commented May 8, 2025

@hacker-hackman I probably would go for feat or introduce a new type like upstream

hacker-hackman commented May 12, 2025

In this specific case, it was indeed a low-risk sync with the upstream repository, containing only formatting and type checking changes. Thanks for the insight!

GabenGar commented May 12, 2025

Just go for chore when dealing with merges/sync. Or create a separate sync type.

Author

qoomon commented May 13, 2025

@GabenGar again I would highly recommend to NOT use chore for syncs from repository external sources. It should reflect what has been synched especially if you sync feat or fix commits. If you do a regular merge, within the sam repo and history chore would be okay, however I would stick with the default merge message.

AlphaHasher commented May 18, 2025

Typo in heading: Inital Commit

Author

qoomon commented May 19, 2025

@AlphaHasher thx, it's fixed.

tamXinchao commented May 20, 2025

thanks for this. It really what i need now

yasithS commented May 30, 2025

really helpful thanks !!!

Author

qoomon commented May 30, 2025

❤️

qoomon/conventional-commits-cheatsheet.md

Conventional Commit Messages

Commit Message Formats

General Commit

Merge Commit

Revert Commit

Initial Commit

Types

Scopes

Breaking Changes Indicator

Description

Body

Footer

Versioning

Examples

Git Hook Scripts to ensure commit message header format

commit-msg Hook (local)

pre-receive Hook (server side)

References

qoomon commented Feb 27, 2025

Uh oh!

goyalyashpal commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qoomon commented Feb 27, 2025

Uh oh!

goyalyashpal commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qoomon commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

barraIhsan commented Mar 9, 2025

Uh oh!

qoomon commented Mar 9, 2025

Uh oh!

barraIhsan commented Mar 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

barraIhsan commented Mar 9, 2025

Uh oh!

qoomon commented Mar 9, 2025

Uh oh!

qoomon commented Mar 9, 2025

Uh oh!

barraIhsan commented Mar 9, 2025

Uh oh!

qoomon commented Mar 9, 2025

Uh oh!

barraIhsan commented Mar 9, 2025

Uh oh!

muzaffaar commented Apr 8, 2025

Uh oh!

qoomon commented Apr 10, 2025

Uh oh!

malihehmoradi commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qoomon commented Apr 22, 2025

Uh oh!

qoomon commented Apr 24, 2025

Uh oh!

hacker-hackman commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qoomon commented May 8, 2025

Uh oh!

qoomon commented May 8, 2025

Uh oh!

hacker-hackman commented May 12, 2025

Uh oh!

GabenGar commented May 12, 2025

Uh oh!

qoomon commented May 13, 2025

Uh oh!

AlphaHasher commented May 18, 2025

Uh oh!

qoomon commented May 19, 2025

Uh oh!

tamXinchao commented May 20, 2025

goyalyashpal commented Feb 27, 2025 •

edited

Loading

goyalyashpal commented Feb 27, 2025 •

edited

Loading

qoomon commented Feb 27, 2025 •

edited

Loading

barraIhsan commented Mar 9, 2025 •

edited

Loading

malihehmoradi commented Apr 22, 2025 •

edited

Loading

hacker-hackman commented May 8, 2025 •

edited

Loading