Git Commit Message Template: Best Practices and Examples

A good Git commit message has a short subject line (about 50 characters, imperative mood), a blank line, then a body that explains what changed and why, wrapped at 72 characters. To make your whole team follow that format, save a template file and point Git to it with git config --global commit.template ~/.gitmessage.txt: Git then pre-fills your editor with it on every git commit.

Git commit message template (copy and paste)

Save this file as ~/.gitmessage.txt. Lines that start with # are comments: Git removes them from the final message.

# <type>(<optional scope>): <subject, imperative, max 50 chars>
# Example: fix(auth): reject empty passwords on login

# Body: what changed and why (not how). Wrap at 72 characters.

# Footer: issue references, breaking changes, co-authors.
# Refs: #123
# BREAKING CHANGE: <what breaks and how to migrate>
# Co-authored-by: Name <email@example.com>

Then tell Git to use it:

# For all your repositories
git config --global commit.template ~/.gitmessage.txt

# Or for the current repository only (path relative to the repository root)
git config commit.template .gitmessage.txt

How the template behaves, per the git commit documentation:

• It only appears when Git opens your editor, so with a plain git commit. It has no effect with git commit -m or -F.
• If you close the editor without changing the template, Git aborts the commit.
• git commit --template=<file> uses another template for a single commit.

You can also add team-specific reminders to the template, for example how to reference tickets or which pull request or merge request the commit belongs to.

How to write a multi-line commit message with git commit -m

You do not need the editor for a subject plus a body. Each -m becomes its own paragraph, separated by a blank line:

git commit -m "fix(auth): reject empty passwords on login" \
  -m "The login endpoint accepted an empty password and returned a 500. Validate the field before calling the auth service." \
  -m "Refs: #123"

Git commit message examples

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

# GITHUB COMMIT MESSAGE TEMPLATE EXAMPLES

## 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

Importance of Clear Git Commit Messages

Clear, well-structured Git commit messages play a crucial role in the development process. They offer context for every change, making project management and collaboration more streamlined. By explaining the reasons behind updates, these messages prevent confusion and help teams maintain a solid version history.

Git Commit Messages Checklist

Enhancing Project Management and Collaboration

Good commit messages can significantly boost teamwork and project organization:

• Clarity and Purpose: Each message quickly tells others what has changed and why it was needed. This reduces onboarding times for new developers and helps existing contributors revisit the codebase with minimal friction.
• Simplifying Code Reviews: A well-written message gives reviewers insight into the scope and objective of a change, making it easier to focus on the code itself.
• Better Teamwork: Detailed commit notes improve communication by illustrating how everyone’s work fits together.

For more detailed guidelines, refer to Git Commit Guidelines.

Benefits for Code Tracking and Version Control

Commit messages also act as your project’s historical breadcrumbs:

• Traceability: It’s easier to backtrack changes and figure out which commit introduced an issue.
• Simple History Navigation: Clear messages let you search for specific fixes or features when the repository grows.
• Smooth Automation: Tools like continuous integration or release pipelines often rely on commit messages to trigger certain actions or generate notes.

Check out Git Documentation on Commit Messages for more information.

Following best practices in writing commit messages helps keep the repository organized, fosters clearer communication, and improves overall productivity for the entire team.

Part 1: Understanding Git Commit Messages

What is a Git Commit Message?

A Git commit message is a short note that goes with each commit in a Git repository. It shows what was changed and explains why those changes were made, serving as an important piece of documentation in your version control process.

• Definition and Purpose: Every commit message clarifies the motivation behind a particular change, helping current and future developers understand the reasoning behind edits when they look back at the project’s history. Atlassian Git Tutorials

• Anatomy of a Commit Message: Generally, a well-written commit message has three parts: a subject line, a body, and a footer. The subject line sums up the changes, the body dives into the details, and the footer can include extra data like issue IDs or references. Conventional Commits

Providing this level of detail is particularly helpful when dealing with complex projects, since it clarifies why certain paths were taken. Maintaining informative commit messages makes your version history a valuable resource for the entire team.

Why Git Commit Messages Matter

Beyond day-to-day coding tasks, commit messages play a significant role in the health of a software project:

• Streamlining Code Reviews: Explaining the scope and purpose of changes helps reviewers provide better feedback.
• Easier Debugging and Troubleshooting: A well-documented commit history accelerates the process of finding when and how bugs were introduced.
• Project Onboarding: New contributors gain insights into the evolution and decision-making behind the code.
• Workflow Automation: Many CI/CD pipelines rely on commit messages for actions like generating changelogs or deploying features.

By consistently writing informative commit messages, developers keep the repository’s history an asset rather than a hindrance.

Part 2: Structure of a Git Commit Message

Subject Line

Each commit message starts with a subject line that briefly captures the essence of your changes. It gives teammates a quick snapshot of the commit’s purpose.

• Concise Summary (50 characters max): Keep your subject line short—ideally no more than 50 characters—so it’s easy to read in various Git tools. How to Write a Git Commit Message

Body

The body of your commit message can include technical details, design reasons, or other relevant background that shaped the changes you made. Writing Good Commit Messages

• Referencing Issues or Pull Requests: If possible, mention any related issues or PRs to provide additional context and keep the broader discussion linked. Referencing Issues in Commits

• Paragraph Breaks: Use distinct paragraphs for different points to maintain clarity. This makes it easier for others to scan and understand your message. Commit Message Guidelines

Footer

In the footer, you can list any relevant metadata:

(See also Sign-off in Commit Messages for more details.)

• Signed-off-by: Some teams require a “Signed-off-by” line in the footer. This is particularly important for projects adhering to 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

Clear and concise commit messages can make your codebase significantly easier to maintain and review. Below are some suggestions:

• Be Specific: Avoid vague text. Summarize the change precisely and mention why it was needed. Effective Commit Messages
• Active Voice & Present Tense: Opt for a direct, present-tense style (e.g., “Fix bug” rather than “Fixed bug”). It’s more straightforward and common in version control logs. Active Voice in Commit Messages

The Imperative Mood

Many teams recommend writing commit messages in the imperative mood. It keeps messages consistent and clearly states the action the commit will take when applied.

• Why Imperative Mood Matters: Short commands like “Add” or “Fix” set an easy-to-read standard. Imperative Mood in Git Commit Messages
• Examples: “Add new feature,” “Fix layout bug,” etc. Sample Commit Messages

Keep the Formatting Plain

Git stores commit messages as plain text, and most tools (including git log) show them as is. Simple hyphen bullets read well everywhere; heavier Markdown such as headings or tables usually does not. Keep rich formatting for pull request descriptions. GitHub formatting syntax

Part 4: Git Commit Message Best Practices

Crafting strong commit messages blends clarity, brevity, and structure. Below are several tried-and-true best practices.

Keep Messages Short but Descriptive

Aim for a concise message that still conveys the essential changes. Many teams recommend a subject line of up to 50 characters.

Separate Subject and Body with a Blank Line

Placing a blank line between the subject and the body ensures better readability and compatibility with various Git tools.

Use the Body to Explain the “What” and “Why,” Not the “How”

Focus on the reason behind the change rather than the implementation details. The code itself shows how something is done.

Reference Issues and Pull Requests

Linking an issue or PR number helps with traceability, so everyone knows the broader discussion.

Capitalize the Subject Line (Unless You Use Conventional Commits)

A capital letter makes each subject look cleaner. Teams using Conventional Commits usually keep the description lowercase after the type (fix: handle empty input). Pick one style and stick to it.

Avoid Ending the Subject with a Period

It’s unnecessary, and skipping it maintains a uniform style.

Wrap the Body at 72 Characters

A 72-character line width is typical, keeping messages neatly formatted in various tools.

Examples of Good vs. Bad Commit Messages

• Good:

  Fix null pointer exception in login
  
  Users who submitted the login form without credentials triggered a
  null pointer error. Validate the fields before processing the request.
  
  Fixes #123
  

• Bad:

  fixed bug
  

Part 5: Git Commit Message Best Practices Examples

To demonstrate these guidelines, here are some well-crafted commit messages:

• Adding a New Feature

  Add user authentication with JWT
  
  Introduce login and registration endpoints and update the frontend
  components to store and send the token.
  

• Fixing a Bug

  Fix null pointer exception in login
  
  Empty credentials reached the auth service and crashed it. Validate
  the input fields before processing the request.
  
  Fixes #123
  

• Updating Documentation

  Update README with setup instructions
  
  Add the local environment setup and clarify the database
  configuration steps.
  

• Refactoring Code

  Refactor user service into smaller functions
  
  Split the large methods to make the service easier to test. Add unit
  tests to keep the behavior unchanged.
  

• Improving Performance

  Speed up user lookups with an index on email
  
  The user endpoints scanned the whole table. The new index cuts the
  lookup time by about 30% in local benchmarks.
  

Axolo User Experiences

2480+ developers online

Try Axolo for free

Part 6: Automating Git Commit Messages

Automation tools help maintain consistent github commit messages standards, so every commit message remains clear and uniform.

Tools for Enforcing Commit Message Standards

• Commitlint: Checks if messages follow certain formats (like conventional commits). Commitlint Documentation

  

  Screenshot of how Commitlint works

• Husky: Runs Git hooks easily, often combined with Commitlint to validate messages. Husky Documentation

• Git Hooks: Custom scripts triggered at specific points in the Git workflow (e.g., pre-commit, commit-msg). Git Hooks Documentation

Setting Up Commit Message Templates

• Creating a Commit Template in Git:

  Using Git Commit Templates

• Examples and Customization:

  Commit Message Template Examples

Part 7: Common Pitfalls and How to Avoid Them

Even with guidelines, it’s easy to slip into bad habits. Here are some frequent pitfalls:

Vague Commit Messages

Phrases like “update code” or “fix stuff” don’t explain anything. Be precise about the change and its motivation.

Overly Detailed Commit Messages

On the flip side, massive blocks of text can obscure the main idea. Strike a balance between clarity and brevity.

Ignoring the Subject Line

Always give a clear, concise subject line. This is the first thing people see and should summarize the commit at a glance.

By avoiding these common errors, you’ll maintain a clean, navigable history.

Part 8: Git Commit Message Conventions

Conventions add clarity to your project’s commit history, simplifying how changes are categorized and understood.

Conventional Commits

Conventional Commits (current version: 1.0.0) is the most widely used commit message convention. The format is:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• fix: is a bug fix and maps to a PATCH release in Semantic Versioning.
• feat: is a new feature and maps to a MINOR release.
• A ! after the type or scope (feat(api)!:), or a BREAKING CHANGE: footer, marks a breaking change and maps to a MAJOR release.
• Other types are allowed. The common set, from the Angular convention used by commitlint's default config, is build, chore, ci, docs, style, refactor, perf and test.

Semantic Commit Messages

Align your commit messages with semantic commits. Tools such as semantic-release read Conventional Commits to bump the version and write the changelog automatically. Semantic Versioning

Customizing Commit Message Guidelines for Your Team

Adopt existing formats or tailor them to your workflow. The goal is to keep messages uniform and easy to parse. A commit convention can unify everyone’s approach.

Tools and Resources for Better Commit Messaging

Besides automating and standardizing your github commit message best practices, here are additional tools and references:

1. Axolo for code review
   Use Axolo to open Slack channels for each PR, keeping commit and update commit message discussions centralized. To compare it with other tools, see the best GitHub Slack integrations.

   code review

2. GitHub Code Review Best Practices
   Read up on github code review best practices to see how commit messages fit into broader development cycles.

3. Pull Request Guides
   If your team debates pull request vs merge request or wonders what is a pull request, aligning commit conventions with your PR workflow ensures clarity. This also helps optimize your github pull request workflow.

4. GitHub Templates
   A github pull request template works in tandem with standardized github commit messages.

5. GitHub Draft PR
   A github draft pr lets you experiment before finalizing commits.

6. GitHub Actions on Pull Request
   Use github actions on pull request to automate tasks like linting or commit checks.

Embracing these resources encourages a mindset of continuous improvement, so you can adjust your commit conventions as your project’s needs evolve.

Part 9: Advanced Git Commit Message Techniques

For bigger teams or open source initiatives, advanced methods can further enhance clarity and collaboration.

Using Emojis in Commit Messages

Adding emojis can make commit messages more visually distinctive, hinting at their nature at a glance. Using Emojis in Commits

Crafting Commit Messages for Automated Tools

Well-structured messages can trigger automatic release notes or build processes, especially with CI/CD setups.

Commit Messages in Open Source Projects

Different open source communities have unique commit rules. Following them helps you blend in more smoothly. Open Source Commit Guidelines

Conclusion

Recap of Key Points

We’ve covered everything from basic structure to commit message best practices and advanced techniques for git commit messages. Solid commit messages:

• Help colleagues review and understand the history of changes
• Speed up bug tracing and new team member onboarding
• Integrate seamlessly into automation, pipelines, and versioning

Importance of Consistent Commit Messages

When commit messages follow a uniform style, the entire project benefits from easier reviews, better collaboration, and improved troubleshooting. Adopting these commit message conventions—whether you follow a strict git commit message convention or a simpler approach—can unify how changes are tracked.

Ongoing Improvement and Adaptation

• Review Practices Regularly: Check if your message guidelines fit your current workflow.
• Collect Team Feedback: Let everyone weigh in on improvements.
• Adopt New Tools or Techniques: Try out new automation services or updated standards.
• Commit to Excellence: See commit messages as a key part of quality development, not just an afterthought.

By keeping these points in mind, you transform your commit history into a robust asset for the entire team.

Appendix

Glossary of Terms

• Commit: A set of changes recorded in a Git repository at a specific point in time.
• Commit Message: Text accompanying a commit that describes the changes and their motivation.
• Conventional Commits: A simple standard for commit messages based on specific prefixes (feat, fix, docs, etc.).
• CI/CD: Continuous Integration and Continuous Deployment/Delivery, automating builds, tests, and releases.
• Semantic Versioning: A versioning method using major.minor.patch to reflect the nature of changes.

Additional Resources and References

• Conventional Commits

• Git Commit Guidelines

• Effective Commit Messages

• Markdown Guide

Templates and Checklists for Git Commit Messages

• Commit Message Template Examples

• Commitlint Documentation

Use these to keep your commit messages structured, clear, and valuable over the long haul. They’ll help you maintain high standards and streamline development in any project.