How to use Git Conventional Commits Messages

Core Structure of Git Conventional Commit Message

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:

   

   • 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:

   

   • type: refactor

   • scope: database

   • subject: improve connection handling on shutdown

   • body: Explanation.

   • footer: Issue reference.

4. Breaking change (shown in the footer):

   

   
   

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

• Format:

  

• 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!