Skip to content

Instantly share code, notes, and snippets.

@joshbuchea

joshbuchea/semantic-commit-messages.md

Last active October 29, 2025 05:20
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:

@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