Skip to main content

Commit Messages Best Practices

Introduction​

Commit messages are an integral part of the software development process. They provide context about changes made to a project, making it easier to understand what happened and why. This tutorial will guide you through the best practices for writing commit messages.

Importance of Commit Messages​

Commit messages serve several crucial purposes:

  1. They provide context for the changes made in a commit.
  2. They allow other contributors to understand why a certain change was made.
  3. They enable project maintainers to generate changelog easily.

By following some simple best practices, you can write more useful and effective commit messages.

Structure of a Commit Message​

A commit message consists of three distinct parts separated by a blank line: the title, an optional body/content, and an optional footer. The layout looks like this:

type(scope): subject

body

footer
  1. Type: This contains the type of commit (feat, fix, docs, etc.)
  2. Scope: This is optional and refers to the module or component affected by the change.
  3. Subject: This is a brief description of the change.
  4. Body: This is where you provide a detailed description of the change. You can discuss the rationale for the change, differences from the previous behavior, etc. It should be separated from the subject line by a blank line.
  5. Footer: This is where you can reference any issues that this commit closes.

Best Practices​

Here are a few best practices to follow while writing commit messages:

  • Make Your Commit Atomic: Each commit should represent a single logical change. Avoid making multiple changes in a single commit.

  • Use the Imperative Mood: Write your commit message in the imperative mood: "Fix bug" and not "Fixed bug" or "Fixes bug".

  • First Line is the Subject: The first line of the commit message should be a short description (50 characters max) and should skip the full stop.

  • Use the Body to Explain What and Why: Use the body to explain what changes you have made and why you made them.

  • Reference Issues in the Footer: If your commit is related to an issue, reference it in the footer.

  • Use a Consistent Style: Whatever style you choose for your commit messages, be consistent.

Conclusion​

Writing effective commit messages is a skill that takes time and practice to master. By following these best practices, you can write commit messages that are informative, easy to read, and useful for other project contributors. Always remember that the primary purpose of a commit message is to help your future self and your teammates understand why a particular change was made.