Skip to main content

How to use Git Conventional Commits Messages

Updated 4 min readMarkdown
How to use Git Conventional Commits Messages

Core Structure of Git Conventional Commit Message

<type>(<scope>): <subject>
<BLANK LINE>
<body> (optional)
<BLANK LINE>
<footer> (optional>
  1. type: Describes the category of the commit (e.g., feat, fix, docs, style, refactor, test, build, ci, perf, chore, revert).

  2. scope (optional): A short identifier for the section or module of the codebase that was changed. Placed inside parentheses immediately after the type.

  3. subject: A brief summary of the changes (preferably no more than ~72 characters). Written in the imperative mood (“change”, “add”, “fix”, not “changed”, “added”, “fixed”).

  4. body (optional): Used for more extensive descriptions of what and why. Explains the changes in detail if needed.

  5. footer (optional): Commonly used to reference issues (e.g., “Closes #123”) or to signal a BREAKING CHANGE.

Common Types

  • feat: A new feature.

  • fix: A bug fix.

  • docs: Documentation changes (e.g., README updates).

  • style: Changes that don’t affect functionality (whitespace, formatting, etc.).

  • refactor: Code changes that neither fix a bug nor add a feature.

  • perf: Changes that improve performance.

  • test: Adding or correcting tests.

  • build: Changes that affect the build system or dependencies.

  • ci: Changes to CI configuration (GitHub Actions, Jenkins, etc.).

  • chore: Routine task changes (e.g., updating .gitignore, minor cleanup).

  • revert: Reverts a previous commit.

Examples

  1. With a scope:

    feat(auth): add JWT verification for user login
    
    • type: feat

    • scope: auth

    • subject: add JWT verification for user login

    • Telling your team you’ve added a feature to the authentication module.

  2. Without a scope:

    fix: handle null pointer exception in login flow
    
    • type: fix

    • subject: handle null pointer exception in login flow

  3. With body and footer:

    refactor(database): improve connection handling on shutdown
    
    This refactor ensures connections are closed gracefully to prevent memory leaks under high-load scenarios.
    
    Closes #123
    
    • type: refactor

    • scope: database

    • subject: improve connection handling on shutdown

    • body: Explanation.

    • footer: Issue reference.

  4. Breaking change (shown in the footer):

    feat(auth): remove deprecated Oauth 1.0 support
    
    BREAKING CHANGE: The commit removes OAuth 1.0. All applications must mirgate to Oauth 2.0 endpoints.
    

Best Practices

  1. Scope:

    • Use parentheses for the scope if you want to call out the specific part of the code changed (e.g., (auth), (database)).

    • Keep it short—one word or small phrase.

  2. Subject:

    • Keep the subject line short (≤ 72 characters).

    • Use imperative tense (“add”, “update”, “fix”) rather than “added”, “updating”, “fixed”.

    • Avoid punctuation at the end of the subject (no period needed).

  3. Body:

    • Optional but recommended if you need to explain why a change was made, not just what.

    • Wrap text at around 72 characters for readability.

  4. Footer:

    • Use for references to issues (Closes #123, Fixes #45) or for large changes that break backward compatibility (BREAKING CHANGE:).

    • Keep it short and to the point.

  5. When to Use Breaking Change:

    • If any commit requires users or developers to update their code, environment, or configuration for the software to continue working correctly, it’s a BREAKING CHANGE.

    • Example: removing a deprecated feature, changing a method signature, or altering a configuration format.

  6. Consistency:

    • Align with your team’s or project’s guidelines for scopes and how detailed the body should be.

    • Enforce a commit message style checker (like commitlint) for consistency

Quick Reference Summary

<type>(<scope>): <subject>

<body>

<footer>
  • Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

  • Scope (optional): Define the part of the code changed (in parentheses).

  • Subject: Short imperative description (≤ 72 chars).

  • Body (optional): Longer explanation of changes if necessary.

  • Footer (optional): References or BREAKING CHANGE notes.

Use this cheat sheet to keep your commit messages consistent, clear, and meaningful!

3 views

No comments yet. Be the first to comment.