Ultimate Guide to Git Commit Message Templates: Best Practices and Examples

TLDR: Git Commit Message template

Use the following examples to craft clear and effective Git commit messages for various scenarios:

## Commit message with description and breaking change footer
feat: allow provided config object to extend other configs

BREAKING CHANGE: 'extends' key in config file is now used for extending other config files.

## Commit message with ! to draw attention to a breaking change
feat!: send an email to the customer when a product is shipped

## Commit message with scope and ! to draw attention to a breaking change
feat(api)!: send an email to the customer when a product is shipped

## Commit message with both ! and BREAKING CHANGE footer
chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

## Commit message with no body
docs: correct spelling of CHANGELOG

## Commit message with scope
feat(lang): add Polish language

## Commit message with multi-paragraph body and multiple footers
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from the latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

## Commit message for a minor bug fix
fix(ui): resolve issue with dropdown menu alignment

The dropdown menu was misaligned on the profile page due to CSS conflicts.
Updated the styles to ensure proper alignment across different screen sizes.
Fixes issue #789.

## Commit message for adding a new test
test: add unit tests for user authentication module

Added unit tests for the user authentication module to cover login, registration, and token verification functionalities.
Ensured all tests pass with the new authentication logic.
Refs: #456

## Commit message for a configuration change
chore(config): update ESLint configuration to support latest standards

Updated the ESLint configuration to support the latest JavaScript standards and best practices.
Included new rules for code formatting and improved error detection.
Reviewed-by: A, B

Introduction

Importance of Clear Git Commit Messages

Clear and concise Git commit messages are essential in the software development lifecycle. They provide context and understanding of changes, aiding in project management, collaboration, and maintaining a clean version history. Here’s why they matter.

Git Commit Messages checklist

Enhancing Project Management and Collaboration

Effective commit messages can significantly improve project management and team collaboration. Here's how:

• Context and Clarity: Each commit message offers a snapshot of what changes were made and why. This context is invaluable for anyone reviewing the project's history or understanding the codebase's evolution. Clear messages reduce onboarding time for new team members and make revisiting old code easier for existing members.
• Efficient Code Reviews: Well-written commit messages streamline the code review process. Reviewers can quickly grasp the purpose and scope of changes, allowing for more focused reviews.
• Enhanced Collaboration: Clear commit messages foster better communication among multiple developers working on the same project. They help synchronize efforts, understand each team member’s contributions, and avoid redundant work.

For more detailed guidelines, refer to the Git Commit Guidelines.

Benefits for Code Tracking and Version Control

Commit messages are essential for tracking changes and maintaining an organized version control history. Here are the benefits:

• Traceability: Clear commit messages make it easy to trace the origin of specific changes. This is crucial for debugging, as developers can pinpoint when and why a particular change was made.
• History Navigation: With well-structured commit messages, navigating through the history of the repository becomes straightforward. Developers can quickly find specific changes related to a bug fix, feature implementation, or refactor.
• Automated Tools Integration: Many continuous integration (CI) and deployment tools rely on commit messages to trigger actions or generate release notes. Clear and consistent messages ensure these tools function correctly and provide meaningful outputs.

For an in-depth understanding, check out the Git Documentation on Commit Messages.

By adhering to best practices for writing Git commit messages, developers can enhance the overall efficiency and effectiveness of their project workflows, ensuring that the version control history is a valuable resource for everyone involved in the project.

Part 1: Understanding Git Commit Messages

What is a Git Commit Message?

A Git commit message is a brief text that accompanies each commit in a Git repository. It provides a snapshot of what changes were made and why, serving as an essential piece of documentation within the version control system.

• Definition and Purpose: A Git commit message serves to explain the context and intent of the changes made in a particular commit. This makes it easier for other developers (and your future self) to understand the rationale behind changes when reviewing the project history.
  • Atlassian Git Tutorials
• Anatomy of a Commit Message: A well-structured commit message typically consists of a subject line, a body, and a footer. The subject line is a brief summary of the changes, the body provides more detailed information, and the footer includes any relevant metadata, such as issue references.
  • Conventional Commits

Why Git Commit Messages Matter

Beyond their role in basic project management, Git commit messages play several critical roles in the development lifecycle and overall project health.

• Facilitating Code Reviews: Clear commit messages make it easier for reviewers to understand the scope and purpose of changes. This leads to more effective and efficient code reviews.
  • The Importance of Commit Messages
• Debugging and Troubleshooting: When bugs arise, a well-documented commit history allows developers to trace changes that might have introduced issues. This can significantly speed up the debugging process.
• Project Onboarding: For new team members, commit messages provide valuable insights into the project's evolution and decision-making processes, easing the onboarding process.
• Automating Workflows: Many CI/CD systems and release tools use commit messages to trigger actions, generate changelogs, and automate parts of the deployment process. Consistent messaging ensures these tools work effectively.
• Historical Context: Over time, commit messages build a historical narrative of the project. This context is invaluable for understanding why certain decisions were made, especially in complex projects.

By consistently writing informative commit messages, developers can ensure that the version control history remains a valuable resource for everyone involved in the project.

Part 2: Structure of a Git Commit Message

Subject Line

The subject line is the first part of a commit message and should provide a brief summary of the changes made. It sets the tone for the rest of the message and helps reviewers quickly understand the purpose of the commit.

• Brief Summary of the Commit (50 characters max): The subject line should be concise, ideally limited to 50 characters, to ensure readability in various Git tools and interfaces.
  • How to Write a Git Commit Message

Body

The body of a commit message provides detailed information about the changes made. It explains the "what" and "why" behind the changes, offering valuable context for reviewers and future maintainers.

• Detailed Explanation of What and Why: The body should elaborate on the changes introduced by the commit, explaining what was done and why it was necessary. This section can include technical details, design decisions, and any relevant background information.
  • Writing Good Commit Messages
• Reference to Relevant Issues or Pull Requests: Whenever possible, include references to related issues or pull requests. This helps link the commit to broader project discussions and provides additional context.
  • Referencing Issues in Commits
• Separate Paragraphs for Different Points: To enhance readability, separate different points or topics within the body into distinct paragraphs. This makes the message easier to scan and understand.
  • Commit Message Guidelines

Footer

The footer of a commit message includes additional metadata that may be relevant to the commit. This can include co-authors, issue tracking information, and other pertinent details.

• Metadata Like Co-Authors, Issue Tracking, etc.: The footer can be used to acknowledge co-authors, track related issues, or include other relevant metadata. This helps maintain a clear and comprehensive record of contributions.
  • Sign-off in Commit Messages
• Sign-off Details: When required, include a "Signed-off-by" line in the footer to indicate who authored or reviewed the commit. This is particularly useful in projects that follow the Developer Certificate of Origin (DCO).
  • Git Documentation on Sign-offs

Part 3: Writing Effective Git Commit Messages

Tips for Crafting Clear and Concise Messages

Writing clear and concise commit messages is an art that can significantly improve the readability and maintainability of your codebase. Here are some tips to help you craft effective commit messages:

• Be Precise and to the Point: Avoid vague language and focus on specific changes. Clearly describe what the commit does.
  • Effective Commit Messages
• Use Active Voice and Present Tense: Writing in active voice and present tense makes commit messages more direct and easier to understand.
  • Active Voice in Commit Messages

The Imperative Mood

Using the imperative mood in commit messages is a widely recommended practice. It helps maintain a consistent and professional tone.

• Explanation and Importance: The imperative mood (e.g., "Fix bug," "Add feature") gives a command and clearly states what the commit does. This approach aligns with how commit messages are interpreted: they describe what applying the commit will do.
  • Imperative Mood in Git Commit Messages
• Examples of Imperative Mood in Commit Messages: Examples help illustrate how to effectively use the imperative mood in your commit messages.
  • Sample Commit Messages

Using Markdown for Formatting

Markdown is a lightweight markup language that can be used to format commit messages, making them more readable and organized.

• Adding Bullet Points and Code Blocks: Use bullet points to list changes and code blocks to highlight code snippets. This enhances the clarity and readability of the commit message.
  • Markdown Guide
• Enhancing Readability: Utilizing Markdown formatting can significantly improve the visual structure of your commit messages, making them easier to scan and understand.
  • GitHub Flavored Markdown

Part 4: Git Commit Message Best Practices

Writing great commit messages is an art that combines clarity, brevity, and structure. Here are some best practices to follow, ensuring your commit messages are both informative and efficient.

Keep Messages Short but Descriptive

Your commit message should be concise yet descriptive enough to convey the main change. Aim for subject lines under 50 characters and body text that provides necessary details without being overly verbose.

• Optimal Length for Subject Lines and Bodies: Keep your subject line to 50 characters or less to ensure it fits nicely in various Git tools and interfaces.
  • Git Commit Message Length

Separate Subject and Body with a Blank Line

Always separate the subject from the body with a blank line. This enhances readability and ensures that tools parsing your commits can do so accurately.

Use the Body to Explain What and Why, Not How

The body of your commit message should focus on what changes were made and why they were necessary, not on how the changes were implemented. This keeps the message concise and focused.

Reference Issues and Pull Requests

Linking to relevant issues or pull requests provides context and helps trace the history of the changes. It’s a good practice to reference issues directly in the commit message.

• Linking to GitHub or GitLab Issues: Use autolinked references to connect your commits to issues and PRs.
  • GitHub Autolinked References

Capitalize the Subject Line

Always start the subject line with a capital letter. This is a simple yet effective way to keep your commit messages looking professional and consistent.

Do Not End the Subject Line with a Period

Avoid ending the subject line with a period. It’s unnecessary and goes against the convention of keeping the subject line brief and to the point.

Wrap the Body at 72 Characters

For better readability, wrap the body text at 72 characters. This makes your commit message easier to read in various interfaces, especially those that display text in a narrow column.

Examples of Good vs. Bad Commit Messages

Seeing examples can help you understand these best practices in action. Here are some comparisons to illustrate good and bad commit messages.

• Good Commit Messages: Clear, concise, and informative.

  • Example 1:

    Subject: Fix null pointer exception in login
    
    Body:
    Resolved a null pointer exception that occurred when the user attempted to log in without entering credentials.
    Added validation to check for null values before processing login requests.
    Fixes issue #123.
    

  • Example 2:

    Subject: Add search functionality to product page
    
    Body:
    Implemented a search feature on the product page allowing users to filter products by name, category, and price.
    Updated UI components to accommodate the new search bar.
    References issue #456.
    

• Bad Commit Messages: Vague, unstructured, or overly detailed.

  • Example 1:

    Subject: Fix bug
    
    Body:
    Fixed a bug that was causing issues.
    

  • Example 2:

    Subject: Update code
    
    Body:
    Updated some parts of the code. Changed various files and fixed some bugs that were reported.
    

  • Example 3:

    Subject: Implemented new feature for product search which includes multiple parameters like name, category, and price. Also, updated the UI to accommodate this feature and added a new search bar at the top of the product page for better user experience. This change required modifying several components and adding new tests to ensure everything works as expected.
    

By following these best practices, you'll ensure your commit messages are a valuable part of your project's documentation and history, aiding both current and future developers in understanding the codebase.

Part 5: Git Commit Message Best Practices Examples

To make these best practices more tangible, here are some examples of well-crafted commit messages for different scenarios. Each example includes a subject line and a detailed body that adheres to the guidelines we've discussed.

• Example 1: Adding a New Feature

Subject: Add user authentication feature

Body:
Implemented user authentication functionality using JWT.
Added login and registration endpoints.
Updated frontend to handle authentication.

• Example 2: Fixing a Bug

Subject: Fix null pointer exception in login

Body:
Resolved a null pointer exception that occurred when the user attempted to log in without entering credentials.
Added validation to check for null values before processing login requests.
Fixes issue #123.

• Example 3: Updating Documentation

Subject: Update README with setup instructions

Body:
Added detailed setup instructions for the development environment.
Included steps for database setup and initial configuration.
Clarified existing instructions for clarity.

• Example 4: Refactoring Code

Subject: Refactor user service for better readability

Body:
Refactored the user service to improve code readability and maintainability.
Split large methods into smaller, more manageable functions.
Added unit tests to ensure the refactoring did not introduce any bugs.

• Example 5: Improving Performance

Subject: Optimize database queries for user endpoints

Body:
Optimized database queries to improve performance of user-related endpoints.
Reduced query execution time by adding appropriate indexes.
Updated ORM configurations to use more efficient query methods.
Performance benchmarks show a 30% improvement in response times.

Axolo User Experiences

2480+ developers online

Tyler

Code quality has improved, engineers have a better understanding of what their colleagues are working on, and code is getting shipped much faster. Time from pull request open to review to merge is WAY faster, and engagement with reviews is much higher for our team. Axolo's team is also unbelievably fast in resolving issues when we run into them. Pleasure to work with them.

Read more Axolo reviews ->

Jacob

Axolo is an incredible tool for connecting PRs with our everyday engineering discussion on Slack. It integrates seamlessly and makes it so as a manager, I never lose track of my engineers' work. For my engineers, it allows them to collaborate without losing a thread in different contexts. Overall it keeps us moving swiftly throughout the sprint and continuously reviewing and merging code!

Read more Axolo reviews ->

Dan

Axolo has made it easier to hold developers and QA engineers accountable for reviewing and merging pull requests on a timely basis. Our average PR time-to-merge was 2.40 days before Axolo, this has been reduced to 1.51 days after only using it for 2 weeks.

Read more Axolo reviews ->

Try Axolo for free

Part 6: Automating Git Commit Messages

Automation can help maintain consistency and adherence to best practices in Git commit messages. By using tools and templates, you can enforce standards and make sure every commit message is clear and informative.

Tools for Enforcing Commit Message Standards

There are several tools available to help enforce commit message standards, ensuring that every commit message meets your team's guidelines.

• Commitlint: Commitlint checks if your commit messages meet the conventional commit format. It can be integrated with various CI tools to enforce standards automatically.

  • Commitlint Documentation
    

    Screenshot of how Commit Link works

• Husky: Husky is a tool that allows you to run Git hooks easily. It can be used to enforce commit message conventions by integrating with tools like Commitlint.

  • Husky Documentation

• Git Hooks: Git hooks are scripts that run automatically at specific points in the Git workflow. You can use them to enforce commit message standards, run tests, or perform other checks.

  • Git Hooks Documentation

Setting Up Commit Message Templates

Using commit message templates can help ensure that your commit messages are consistently formatted and include all necessary information.

• Creating and Using a Commit Message Template in Git: You can set up a commit message template in Git to standardize your commit messages. This ensures that every commit message follows a predefined structure.
  • Using Git Commit Templates
• Example Templates and How to Customize Them: There are many examples of commit message templates available online. You can customize these templates to fit your team's specific needs.
  • Commit Message Template Examples

Part 7: Common Pitfalls and How to Avoid Them

Even with the best intentions, it's easy to fall into common pitfalls when writing commit messages. Here are some typical mistakes and how to avoid them, ensuring your commit history remains clear and useful.

Vague Commit Messages

Vague commit messages fail to provide enough information about the changes made, making it difficult for others to understand the purpose and impact of the commit.

• Examples and Why They Are Problematic: Vague messages like "fix stuff" or "update code" are uninformative and do not help in understanding the changes made. They complicate code reviews and future maintenance.
• How to Make Them More Specific: Be precise and descriptive. Explain what was changed and why. Use the commit body to provide additional context if needed.

Overly Detailed Commit Messages

While it's important to provide context, overly detailed commit messages can be just as problematic as vague ones. They can overwhelm readers with unnecessary information.

• Finding the Right Balance: Aim for clarity and conciseness. Provide enough detail to explain the change without overloading the reader with information.
  • Optimal Commit Message Length
• Examples of Concise Yet Informative Messages: Focus on what and why, keeping explanations brief and to the point.
  • Commit Message Examples

Ignoring the Subject Line

The subject line is the most visible part of your commit message. Ignoring its importance can lead to confusion and reduced readability in commit logs.

• Importance of a Clear and Concise Subject: A clear subject line summarizes the commit and makes it easy to understand at a glance. It should be succinct and to the point.
  • Subject Line Best Practices
• Examples of Effective Subject Lines: Compare good and bad subject lines to see the difference. Good subject lines are specific and informative, while bad ones are vague or overly detailed.

By being aware of these common pitfalls and actively working to avoid them, you can ensure your commit messages are clear, concise, and valuable to your team. This practice will significantly enhance the quality and navigability of your project's commit history.

Part 8: Git Commit Message Conventions

Standardizing commit messages with conventions can greatly improve the readability and manageability of your project's history. Let's explore some widely-used conventions and how you can customize them for your team.

Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of.

• Overview and Benefits: Conventional Commits use a simple, structured approach to writing commit messages. This helps automate the release process, generate changelogs, and ensure consistent communication across the team.
  • Conventional Commits
• Types and Examples of Conventional Commits: There are specific types of commit messages, such as feat for new features, fix for bug fixes, and more. Each type has a clear purpose, making it easy to understand the nature of each commit.
  • Commit Types

Semantic Commit Messages

Semantic commit messages follow the principles of semantic versioning. They help in understanding the impact of each commit on the project’s version and automate the versioning process.

• Using Semantic Versioning in Commit Messages: Semantic versioning provides a structured way to increase version numbers based on the type of changes. Using it in commit messages ensures that version numbers accurately reflect the nature of changes.
  • Semantic Versioning
• Examples and Use Cases: Examples include using fix: for bug fixes, feat: for new features, and BREAKING CHANGE: for changes that break backward compatibility. These examples help in automating version bumps and generating release notes.

Customizing Commit Message Guidelines for Your Team

While standardized conventions are useful, customizing them to fit your team’s workflow and preferences can enhance productivity and consistency.

• Establishing and Enforcing Team-Specific Conventions: Create a set of guidelines tailored to your team's needs. This could include specific tags for different types of work, additional metadata requirements, or custom formatting rules.
  • Team Commit Guidelines

By adopting and customizing commit message conventions, you can ensure that your project's commit history is consistent, informative, and easy to manage. This not only improves collaboration within the team but also facilitates automation and enhances the overall quality of the project documentation.

Part 9: Advanced Git Commit Message Techniques

Taking your Git commit messages to the next level involves adopting advanced techniques that can enhance clarity, drive automation, and improve collaboration, especially in larger or open source projects. Let's dive into some of these techniques.

Using Emojis in Commit Messages

Emojis can add a visual element to commit messages, making them more engaging and easier to scan. They can quickly convey the type of change at a glance.

• Benefits and Examples: Emojis help in categorizing commits and making the commit history more readable. For example, 🐛 for bug fixes, ✨ for new features, and 📝 for documentation updates.
  • Using Emojis in Commits
• When and How to Use Emojis Effectively: Use emojis consistently and sparingly. They should enhance readability, not clutter the commit message.

Crafting Commit Messages for Automated Tools

Automating workflows with CI/CD tools can be significantly enhanced by using structured commit messages. This helps in triggering specific actions, generating changelogs, and automating deployments.

• Best Practices for Commit Messages that Trigger CI/CD Actions: Use conventional commit messages to trigger automated processes. For example, fix: can trigger a patch release, while feat: can trigger a minor version bump.
• Examples of Commit Messages for Automated Deployments: Commit messages that integrate with CI/CD pipelines can streamline deployment processes. For example, using [deploy] in the commit message to trigger a deployment pipeline.
  • CI/CD and Commit Messages

Commit Messages in Open Source Projects

Commit messages are crucial in open source projects for maintaining clear and communicative histories that facilitate collaboration among a wide range of contributors.

• Guidelines for Contributing to Open Source: Follow the specific contribution guidelines provided by the open source project. These often include standardized commit message formats to ensure consistency and clarity.
  • Open Source Commit Guidelines
• Examples from Popular Open Source Projects: Many popular projects have detailed guidelines for commit messages. For instance, Kubernetes and Angular have specific conventions to follow.
  • Popular Open Source Projects

By incorporating these advanced techniques into your commit message practices, you can further enhance the quality and utility of your project's commit history. These practices support better automation, clearer communication, and more effective collaboration, especially in larger teams or open source environments.

Conclusion

Recap of Key Points

In this guide, we've explored the crucial elements of writing effective Git commit messages. We've delved into the structure of commit messages, discussed best practices, highlighted common pitfalls, and introduced advanced techniques to elevate your commit messages. By mastering these aspects, you can significantly improve the clarity and utility of your commit history.

Importance of Consistent Commit Messages

Consistent commit messages are the backbone of a well-maintained codebase. They:

• Enhance Collaboration: Clear commit messages ensure that team members can quickly understand changes, making collaboration smoother and more efficient.
• Facilitate Code Reviews: Well-written messages streamline the code review process, allowing reviewers to focus on the quality of the code rather than deciphering the intent behind changes.
• Support Automation: Structured commit messages are crucial for integrating with CI/CD pipelines and other automated tools, enabling seamless deployments and accurate changelogs.
• Aid in Troubleshooting: Detailed and specific messages help in tracing the origins of bugs and understanding the history of changes, making debugging more straightforward.

Encouragement for Ongoing Improvement and Adaptation

The field of software development is dynamic, and so are the best practices for writing commit messages. Here’s how you can stay ahead:

• Regularly Review Practices: Periodically evaluate your commit message guidelines to ensure they align with the latest industry standards and team needs.
• Encourage Team Feedback: Foster an environment where team members can suggest improvements and share insights on what works best for them.
• Adapt to New Tools and Workflows: Stay updated with the latest tools and methodologies that can enhance your commit message practices. Automation tools, in particular, are constantly evolving and can offer new ways to enforce standards and improve consistency.
• Promote a Culture of Excellence: Commit to continuous learning and improvement. Encourage your team to view commit messages not as a chore, but as an integral part of the development process that adds significant value to the project.

By embracing these principles, you can ensure that your commit messages not only document the history of your project effectively but also contribute to a more efficient, collaborative, and high-quality development process. Remember, every commit is a piece of the larger puzzle that makes up your project's history. Make each one count.

Appendix

Glossary of Terms

• Commit: A snapshot of changes made to the codebase at a specific point in time.
• Commit Message: A brief text that accompanies a commit, describing the changes made and the reason for them.
• Conventional Commits: A specification for adding human and machine-readable meaning to commit messages, based on a set of rules.
• CI/CD: Continuous Integration and Continuous Deployment/Delivery. A set of practices and tools that automate the process of code integration and deployment.
• Semantic Versioning: A versioning scheme that uses a three-part version number (major.minor.patch) to convey meaning about the underlying changes.

Additional Resources and References

For further reading and to deepen your understanding of effective commit message practices, here are some valuable resources:

• Conventional Commits
• Git Commit Guidelines
• Effective Commit Messages
• Markdown Guide

Templates and Checklists for Git Commit Messages

Using templates and checklists can help standardize your commit messages, ensuring they are clear, consistent, and informative.

• Commit Message Template Examples
• Commitlint Documentation

By leveraging these resources and tools, you can enhance your commit message practices, contributing to a more efficient and collaborative development process. These templates and guidelines serve as a solid foundation for maintaining high standards in your project's commit history.