Skip to content

Instantly share code, notes, and snippets.

@kvanmol

kvanmol/semantic-commit-messages.md

Forked from joshbuchea/semantic-commit-messages.md
Last active August 28, 2024 16:02
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save kvanmol/8f5ce5d21b3b56134675af6d6d774c7b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save kvanmol/8f5ce5d21b3b56134675af6d6d774c7b to your computer and use it in GitHub Desktop.
Download ZIP
Semantic Commit Messages
Raw
semantic-commit-messages.md

Semantic Commit Messages

Format

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

  • <type>: The type of change (e.g., feat, fix, docs, etc.).
  • <scope>: (optional) The specific part of the project that is affected (e.g., a module, file, or feature).
  • <subject>: A brief description of the change in the present tense.

Example

feat: add CLI
^--^  ^------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

Types of Commit Messages

feat: (Feature)

  • Purpose: Introduces a new feature or enhancement that affects the user-facing functionality.
  • Example: feat: add dark mode support
  • Use Case: Adding a new feature to the application that changes how users interact with it.

fix: (Bug Fix)

  • Purpose: Corrects a bug or an error that affects the user experience or application behavior.
  • Example: fix: correct login error for users with special characters
  • Use Case: Fixing a critical issue that impacts the functionality or user experience.

docs: (Documentation)

  • Purpose: Updates or improves the documentation, including README files, comments, and other documentation-related files.
  • Example: docs: update API documentation for new endpoint
  • Use Case: Modifying documentation to reflect changes in the codebase or to improve clarity.

style: (Styling)

  • Purpose: Changes that affect the formatting or style of the code but do not alter its functionality. This includes things like fixing linting issues or adding missing semi-colons.
  • Example: style: fix indentation in user controller
  • Use Case: Adjusting code formatting to conform to style guidelines without affecting the actual logic.

refactor: (Refactoring)

  • Purpose: Modifies the code structure without changing its external behavior. This includes renaming variables, restructuring functions, or improving code readability.
  • Example: refactor: rename 'temp' variable to 'temporaryValue'
  • Use Case: Improving the internal code structure to make it more maintainable or understandable without changing the code's functionality.

test: (Testing)

  • Purpose: Adds or updates tests, or modifies the test suite. This type does not change the production code.
  • Example: test: add unit tests for user authentication
  • Use Case: Enhancing test coverage or fixing issues in the test code itself.

chore: (Chores)

  • Purpose: Includes changes that do not fall into the other categories. Typically, these changes are related to build processes, configuration files, or other maintenance tasks.
  • Example: chore: update build script for new version
  • Use Case: Performing routine tasks that do not affect the application’s functionality or user-facing features.

Scope - and examples of Scope

  1. Feature-Specific Scope

    • Example: feat(auth): add JWT authentication
    • Explanation: This commit adds a new feature (feat) specifically related to the auth (authentication) module of the project.

  2. Component or Module Scope

    • Example: fix(database): resolve connection timeout issue
    • Explanation: This commit fixes an issue (fix) within the database component, specifically addressing connection timeouts.

  3. File-Specific Scope

    • Example: docs(README): update installation instructions
    • Explanation: This commit updates documentation (docs) specifically in the README file.

  4. Service-Specific Scope

    • Example: refactor(api): improve error handling
    • Explanation: This commit refactors code (refactor) in the api service, focusing on improving error handling.

  5. UI Component Scope

    • Example: style(button): fix padding inconsistency
    • Explanation: This commit addresses a style issue (style) specifically related to the button UI component.

  6. Test Scope

    • Example: test(auth): add unit tests for login flow
    • Explanation: This commit adds tests (test) specifically for the auth module, focusing on the login flow.

When to Use Scope

  • Use scope when a commit is specific to a certain area, module, or component within your project.
  • It's optional, so if a commit is broad or affects multiple areas, you can omit the scope.

Tips and tricks

Use Present Tense

Write the commit message in the present tense as if you are describing what the commit does:

  • Correct: fix: correct login issue
  • Incorrect: fixed: corrected login issue

Avoid Generic Messages

Avoid vague commit messages like "update" or "changes":

  • Avoid: update: make changes
  • Correct: refactor: improve error handling in authentication module

Use Imperative Mood

The imperative mood (commands) is preferred, as it reads like a set of instructions or a command:

  • Correct: add support for multi-language
  • Incorrect: added support for multi-language

Further readings:

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