Skip to content

Instantly share code, notes, and snippets.

@joshbuchea

joshbuchea/semantic-commit-messages.md

Last active October 31, 2025 00:13
Show Gist options
  • Save joshbuchea/6f47e86d2510bce28f8e7f42ae84c716 to your computer and use it in GitHub Desktop.
Save joshbuchea/6f47e86d2510bce28f8e7f42ae84c716 to your computer and use it in GitHub Desktop.
Download ZIP
Semantic Commit Messages
Raw
semantic-commit-messages.md

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:

@djereg
Copy link

djereg commented Nov 20, 2024

I use chore for deleting unsed code.

@tykeal
Copy link

tykeal commented Nov 20, 2024

refactor would be to move currently used code to an unused code path.
chore should be used related to code that is being cleaned out and has no active paths to it. We also use chore when bumping dependency versions without any other code changes needed.

@CLucasrodrigues22
Copy link

Which type can I use to commit a dependency update? I see the build(deps): type often, is it correct?

refactor

@cfgnunes
Copy link

cfgnunes commented Feb 10, 2025 •
edited
Loading

I wanted to share my commit-msg Git hook script that enforces the Conventional Commits standard. This script ensures that all commit messages follow a consistent format, improving readability and maintainability of the project's commit history.

What it does:

  • Validates commit messages against the Conventional Commits format: <type>(<scope>): <subject>.
  • Provides detailed error messages if the commit message doesn't match the expected format.
  • Includes descriptions for each valid commit type to help users understand when to use them.

How to use it:

  1. Copy the script below into your repository's .git/hooks/commit-msg file.
  2. Make the script executable by running: 
    chmod +x .git/hooks/commit-msg
  3. Start committing! The hook will automatically validate your commit messages.

Script:

#!/usr/bin/env bash

# Path to the commit message file (provided by Git).
COMMIT_MSG_FILE=$1

# Ignore automatic commit messages containing ' into ' or 'Merge'.
if grep --quiet --extended-regexp " into |^Merge " "$COMMIT_MSG_FILE"; then
    exit 0
fi

# Read the commit message from the file.
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

CONVENTIONAL_COMMIT_REGEX='^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\([a-zA-Z0-9_.-]+\))?(!)?:\s.*$'

# Check if the commit message matches the regex.
if ! [[ $COMMIT_MSG =~ $CONVENTIONAL_COMMIT_REGEX ]]; then
    echo "ERROR: Commit message does not follow Conventional Commits format."
    echo
    echo "The commit message should be structured as follows:"
    echo "<type>(<optional scope>): <description>"
    echo "[optional body]"
    echo "[optional footer(s)]"
    echo
    echo "Valid types are:"
    echo "  feat:     A new feature."
    echo "  fix:      A bug fix."
    echo "  docs:     Documentation changes."
    echo "  style:    Code style changes (formatting, missing semicolons, etc.)."
    echo "  refactor: Code refactoring (neither fixes a bug nor adds a feature)."
    echo "  test:     Adding or updating tests."
    echo "  chore:    Routine tasks like updating dependencies or build tools."
    echo "  build:    Changes affecting the build system or external dependencies."
    echo "  ci:       Changes to CI configuration files or scripts."
    echo "  perf:     Performance improvements."
    echo "  revert:   Reverting a previous commit."
    echo
    echo "Examples:"
    echo "  feat(auth): add login functionality"
    echo "  fix(api)!: resolve timeout issue"
    echo "  docs(readme): update installation instructions"
    echo
    exit 1
fi

exit 0

@nineneel
Copy link

Thanks for the script! @cfgnunes

@ibnTofajjal
Copy link

Thanks @cfgnunes

@nicholaswmin
Copy link

this is an unnecessarily complex "protocol", most of the keywords have no bearing on semver and are just noise.

@Alluseri
Copy link

Alluseri commented Apr 3, 2025

Thanks! Now I know who to blame for having to use this absolutely pointless and brain-damage-inducing spec.

@cfgnunes
Copy link

cfgnunes commented Apr 3, 2025

@nicholaswmin @Alluseri Conventional Commits do introduce some rules, which might add a bit of overhead.

However, in my humble opinion, they make commit history much more organized—especially in larger projects with multiple contributors. The structure improves readability, maintainability, and even enables automation (like changelog generation).

Since Conventional Commits is still in its early stages, it may evolve to become simpler and more intuitive over time. If people have concerns, they could contribute to the project to help shape its future—rather than just criticizing it. Of course, if it doesn’t suit their workflow, they’re free not to use it. 😉

@nicholaswmin
Copy link

nicholaswmin commented Apr 3, 2025 •
edited
Loading

@cfgnunes I agree with most.

they could contribute to the project to help shape its future—rather than just criticizing it.

My contribution is my feedback - I don't have a moral obligation to fix everything I believe is broken.

The structure improves readability, maintainability, and even enables automation (like change log generation).

I very much agree with the philosophy of the project but i'm very against the idea of having so many keywords. I literally have to look up the appropriate keyword.
And this isn't some critical functionality, it's the just...changelog management.

There is no need to have so many keywords for the vast majority of projects.
There is an ongoing trend since the late 00's to cargo-cult secondary helper bolt-ons to projects, such as this this (then husky then this thin that) that do nothing other than scare juniors off from contributing and/or add unnecessary dependencies and mental noise. This has a name and it's a terrible engineering decision.

Is your project SemVered? Yes? Then you've added another process but it can be justified by the fact it now helps you automate SemVer compliance. Ok fair tradeoff.
Do you need that many keywords to figure that out automatically? No.
Please pay attention to your own contexts instead of jumping onto bandwagons. Process is bad. Don't introduce it unnecessarily or prematurely. If there is one adage that survives every bit of scrutiny without fail its KISS

That being said, I appreciate the reply man. And the authors of CC - the fact I disagree with a part of it doesn't mean anything nore than that.

@cfgnunes
Copy link

cfgnunes commented Apr 3, 2025

@nicholaswmin Great points!

I agree that simplicity is essential, and processes shouldn’t be added without a good reason. While Conventional Commits offers a broad set of keywords to provide flexibility, it's worth considering whether a smaller, more essential subset could cover most cases without unnecessary overhead.

That said, it's important to recognize that Semantic Commit, as it stands today, may not be useful for all types of projects. There’s no silver bullet in software engineering—it’s up to each team to evaluate what truly adds value to their workflow. Dismissing the project as "cargo cult programming" might be unfair; we risk misjudging its real purpose or, worse, falling into a Dunning-Kruger effect, where a lack of deeper understanding leads to oversimplified conclusions.

I believe discussions like these are valuable for refining tools, but at the same time, sometimes debates about tooling create more noise than the tools themselves—lots of talk, little action. Personally, I prefer to focus on building rather than overanalyzing.

Thanks for the exchange of ideas!

@nicholaswmin
Copy link

Ok to make this clear:

  • CC is good
  • The keywords must be drastically reduced

"Dismissing the project as cargo cult programming"

I'm not dismissing the project itself as cargo cult programming; that doesn't make sense.
I'm dismissing the overzealous adoption of unnecessary procecess/tools/conventions prematurely, for no concrete reason other than "I also do that"

@keithpjolley
Copy link

Curious what people do when more than one type of "thing" is done in a single commit. For instance, to polish up some python code before committing I ran RightTyper, Trunk format, and then added in some comments on the code.

"Learn to commit between each task" is good advice but sometimes that horse is already out of the barn.

@harizjet
Copy link

nice script @cfgnunes; but you can also use pre-commit hook to enforce it.

@major-phyo-san
Copy link

Hi friends, if I make some changes like bug fixes and feature addition and I have to update the dependency management code (eg, composer.json, package.json, pom.xml, build.gradle etc) to reflect my release version, what would be the commit message for it. For example, I have a PHP composer package that I develop and maintain. I add a bug fix and a feature. The previous version is "version": "0.0.8", and I need to update my package version to be "version": "0.0.9", what would be the commit message for that composer.json.

@qoomon
Copy link

qoomon commented May 19, 2025 •
edited
Loading

In case you are looking for a more detailed git conventional cheatsheet feel free to have a look at https://gist.github.com/5dfcdf8eec66a051ecd85625518cfd13

@bgiddings
Copy link

I'm probably fighting a hopeless battle here, but I have to try. "Feature" should not be shortened to "feat".

"Feat" is already its own word, and it means "something that requires a lot of skill, strength, courage, etc. to achieve". Some features may be feats, but the vast majority of features are not feats.

@guneyozsan
Copy link

@major-phyo-san I used to use bump version and chore: bump version. But in our current project versioning is updated by CI using git tags so no more specific commits. In your specific example that would make 3 commits:

fix: nasty bug
feat: fancy button
chore: bump version

Side note per "Feat" vs "Feature, "Bug" is actually "a small insect" but anyway. Language is contextual, a collection of symbols interpreted within a context. If you leave the context out all words are useless junk.

@oraclejavanet
Copy link

Thank you for sharing the script! @cfgnunes

@srgpsk
Copy link

srgpsk commented Aug 4, 2025

@keithpjolley Assuming you're working with existing code and consistently running those tools, your code should already be pre-formatted, and any changes introduced would remain within the scope of your feature. Polishing unrelated parts of the code, in my opinion, becomes more of a chore than a meaningful feature.

@joshbuchea @cfgnunes thank you guys!

@ale5000-git
Copy link

I wanted to share my commit-msg Git hook script that enforces the Conventional Commits standard. This script ensures that all commit messages follow a consistent format, improving readability and maintainability of the project's commit history.

What it does:

  • Validates commit messages against the Conventional Commits format: <type>(<scope>): <subject>.
  • Provides detailed error messages if the commit message doesn't match the expected format.
  • Includes descriptions for each valid commit type to help users understand when to use them.

How to use it:

  1. Copy the script below into your repository's .git/hooks/commit-msg file.
  2. Make the script executable by running: 
    chmod +x .git/hooks/commit-msg
  3. Start committing! The hook will automatically validate your commit messages.

Script:

#!/usr/bin/env bash

# Path to the commit message file (provided by Git).
COMMIT_MSG_FILE=$1

# Ignore automatic commit messages containing ' into ' or 'Merge'.
if grep --quiet --extended-regexp " into |^Merge " "$COMMIT_MSG_FILE"; then
    exit 0
fi

# Read the commit message from the file.
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

CONVENTIONAL_COMMIT_REGEX='^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\([a-zA-Z0-9_.-]+\))?(!)?:\s.*$'

# Check if the commit message matches the regex.
if ! [[ $COMMIT_MSG =~ $CONVENTIONAL_COMMIT_REGEX ]]; then
    echo "ERROR: Commit message does not follow Conventional Commits format."
    echo
    echo "The commit message should be structured as follows:"
    echo "<type>(<optional scope>): <description>"
    echo "[optional body]"
    echo "[optional footer(s)]"
    echo
    echo "Valid types are:"
    echo "  feat:     A new feature."
    echo "  fix:      A bug fix."
    echo "  docs:     Documentation changes."
    echo "  style:    Code style changes (formatting, missing semicolons, etc.)."
    echo "  refactor: Code refactoring (neither fixes a bug nor adds a feature)."
    echo "  test:     Adding or updating tests."
    echo "  chore:    Routine tasks like updating dependencies or build tools."
    echo "  build:    Changes affecting the build system or external dependencies."
    echo "  ci:       Changes to CI configuration files or scripts."
    echo "  perf:     Performance improvements."
    echo "  revert:   Reverting a previous commit."
    echo
    echo "Examples:"
    echo "  feat(auth): add login functionality"
    echo "  fix(api)!: resolve timeout issue"
    echo "  docs(readme): update installation instructions"
    echo
    exit 1
fi

exit 0

@cfgnunes
Hi,
can your code for the "commit-msg" Git hook be considered licensed as CC0 (similar to public domain)?

@cfgnunes
Copy link

cfgnunes commented Sep 4, 2025

I wanted to share my commit-msg Git hook script that enforces the Conventional Commits standard. This script ensures that all commit messages follow a consistent format, improving readability and maintainability of the project's commit history.

What it does:

  • Validates commit messages against the Conventional Commits format: <type>(<scope>): <subject>.
  • Provides detailed error messages if the commit message doesn't match the expected format.
  • Includes descriptions for each valid commit type to help users understand when to use them.

How to use it:

  1. Copy the script below into your repository's .git/hooks/commit-msg file.
  2. Make the script executable by running: 
    chmod +x .git/hooks/commit-msg
  3. Start committing! The hook will automatically validate your commit messages.

Script:

#!/usr/bin/env bash

# Path to the commit message file (provided by Git).
COMMIT_MSG_FILE=$1

# Ignore automatic commit messages containing ' into ' or 'Merge'.
if grep --quiet --extended-regexp " into |^Merge " "$COMMIT_MSG_FILE"; then
    exit 0
fi

# Read the commit message from the file.
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

CONVENTIONAL_COMMIT_REGEX='^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\([a-zA-Z0-9_.-]+\))?(!)?:\s.*$'

# Check if the commit message matches the regex.
if ! [[ $COMMIT_MSG =~ $CONVENTIONAL_COMMIT_REGEX ]]; then
    echo "ERROR: Commit message does not follow Conventional Commits format."
    echo
    echo "The commit message should be structured as follows:"
    echo "<type>(<optional scope>): <description>"
    echo "[optional body]"
    echo "[optional footer(s)]"
    echo
    echo "Valid types are:"
    echo "  feat:     A new feature."
    echo "  fix:      A bug fix."
    echo "  docs:     Documentation changes."
    echo "  style:    Code style changes (formatting, missing semicolons, etc.)."
    echo "  refactor: Code refactoring (neither fixes a bug nor adds a feature)."
    echo "  test:     Adding or updating tests."
    echo "  chore:    Routine tasks like updating dependencies or build tools."
    echo "  build:    Changes affecting the build system or external dependencies."
    echo "  ci:       Changes to CI configuration files or scripts."
    echo "  perf:     Performance improvements."
    echo "  revert:   Reverting a previous commit."
    echo
    echo "Examples:"
    echo "  feat(auth): add login functionality"
    echo "  fix(api)!: resolve timeout issue"
    echo "  docs(readme): update installation instructions"
    echo
    exit 1
fi

exit 0

@cfgnunes Hi, can your code for the "commit-msg" Git hook be considered licensed as CC0 (similar to public domain)?

Hi! Yes! please feel free to use the code however you’d like. You are welcome to use, distribute, and modify it without any restrictions.

@tykeal
Copy link

tykeal commented Sep 29, 2025

This is available via gitlint which can be used as a commit-msg hook with pre-commit It's exceedingly flexible as you can define what the valid types are via a configuration file without having to modify code.

@Aliakbar-Hosseinzadeh
Copy link

TL;DR article version:

https://medium.com/@aliakbarhosseinzadeh/how-to-write-better-git-commit-messages-52f42b64b50f

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