Git Commit Message Best Practices and Examples

Introduction
Writing clear and consistent Git commit messages is crucial for maintaining a clean and understandable version control history. This document outlines best
practices, commit message formats, and real-world examples to help you write effective commit messages.

Commit Message Format

Follow the Conventional Commits format:

<type>: <description>

Rules for Commit Messages

1. Use a Consistent Format: Always use <type>: <description> .

2. Use Imperative Mood: Write commit messages as if you are giving a command.
3. Keep It Short and Descriptive: The subject line should be under 50 characters.
4. Use Types to Categorize Commits: Common types include feat , fix , docs , style , refactor , test , chore , perf , ci , build , and revert .
5. Reference Issues or Tickets : Include issue numbers if applicable.
6. Avoid Vague Messages: Be specific about what was changed.

Real-World Scenarios and Examples

1. feat : New Feature

Use when adding new functionality or features.

Scenario:

You are working on an e-commerce platform and have implemented a new feature to filter products by price range.

Example:

feat: add price range filter to product search

2. fix : Bug Fix

Use when fixing a bug or issue.

Scenario:

Users reported that the login page crashes when they enter an invalid email format. You fixed the validation logic.

Example:

fix: validate email format on login page to prevent crashes

3. docs : Documentation Changes

Use when updating documentation.

Scenario:

You updated the API documentation to include new endpoints for the user profile feature.

Example:
 docs: update API docs with user profile endpoints

4. style : Code Style Changes

Use for changes related to formatting, indentation, or code style (no functional changes).

Scenario:

You formatted the codebase using Prettier to ensure consistent styling.

Example:

style: format codebase using Prettier

5. refactor : Code Refactoring

Use when improving code structure without changing functionality.

Scenario:

You noticed that the payment processing code was duplicated across multiple files, so you extracted it into a reusable module.

Example:

refactor: extract payment processing logic into a shared module

6. test : Test Changes

Use when adding or modifying tests.

Scenario:

You added unit tests for the new user registration feature to ensure it works as expected.

Example:

test: add unit tests for user registration feature

7. chore : Maintenance Tasks

Use for routine tasks like dependency updates or tooling changes.

Scenario:

You updated the project dependencies to their latest versions to fix security vulnerabilities.

Example:

chore: update project dependencies to latest versions

8. perf : Performance Improvements

Use for changes that improve performance.

Scenario:

You optimized the database query for fetching user orders, reducing the response time by 50%.
Example:

perf: optimize database query for fetching user orders

9. ci : Continuous Integration Changes

Use for changes to CI/CD pipelines or workflows.

Scenario:

You added a GitHub Actions workflow to automatically run tests on every pull request.

Example:

ci: add GitHub Actions workflow for automated testing

10. build : Build System Changes

Use for changes related to the build process.

Scenario:

You updated the Webpack configuration to support TypeScript compilation.

Example:

build: update Webpack config for TypeScript support

11. revert : Revert a Previous Commit

Use when reverting a previous commit.

Scenario:

A recent feature caused instability in production, so you reverted the commit to restore stability.

Example:

revert: remove experimental feature due to instability

How Often Should You Commit?

1. Commit Small, Logical Changes:

Commit when you complete a small, logical unit of work (e.g., a feature, bug fix, or refactor).
Example: After implementing a new API endpoint, commit with feat: add user registration endpoint .

2. Avoid Large, Unrelated Changes:

Do not bundle unrelated changes into a single commit. For example, fixing a bug and adding a new feature should be two separate commits.

3. Commit Frequently:

Commit often to avoid losing work and to make it easier to track changes.
Example: If you are working on a large feature, commit after completing each subtask (e.g., feat: add user model , feat: add user
registration form ).

4. Commit Before Breaking Changes:

Commit before making significant changes that might break the codebase. This allows you to revert easily if something goes wrong.
Additional Best Practices

1. Write Clear and Descriptive Messages :

Clearly describe what was changed and why.

Example: Instead of fix: bug , write fix: resolve null pointer exception in login service .

2. Use the Body for Detailed Explanations:

If the change is complex, use the commit body to provide additional context.
Example:

feat: add user authentication module

- Implement JWT-based authentication

- Add login and registration endpoints
- Update user model to store hashed passwords

3. Reference Issues or Tickets :

Link your commit to a specific issue or ticket for better traceability.

Example: fix: handle null values in product API (closes #123) .

4. Review Before Committing :

Use git diff to review your changes before committing to ensure you are only committing what you intend to.

5. Squash Commits for Clean History:

If you have multiple small commits for a single feature, squash them into one commit before merging into the main branch.
Example: Use git rebase -i to squash commits.

6. Follow Team Conventions:

If your team has specific commit message conventions, follow them consistently.

Real-World Workflow Example

Scenario:

You are working on a task to add a "Forgot Password" feature to your application.

1. First Commit:

feat: add forgot password form UI

2. Second Commit:

feat: implement forgot password API endpoint

3. Third Commit:

test: add unit tests for forgot password feature

4. Fourth Commit:

docs: update user guide with forgot password instructions

5. Final Commit:

fix: handle email sending errors in forgot password flow

Conclusion

By following these best practices and examples, you can ensure that your Git commit history is clean, consistent, and easy to understand for both yourself and your
team. This will improve collaboration and make it easier to track changes over time.