Commit messages are short descriptions of each commit in a version control system like Git. When you commit changes to your project files, you should provide a message explaining what they do or why you made them.
Commit messages serve as a form of documentation and communication. They play a crucial role in maintaining a clear and organized version history of a project. Learn how to write good commit messages and the other members of your team will appreciate your work even more.
Structure of a Good Commit Message
A good example of a commit message includes four sections: Type, Description, Body, and Footer.
Like so:
<type>: <description>
[optional body]
[optional footer]
Type
The type describes the kind of change made in the present commit. You can use whatever system makes sense to your circumstances. For example, here are some sample keywords you can use to signal each type of change, alongside example use:
- feat: your changes introduce a new feature.
- fix: you fix a bug.
- refactor: your change refactors code without fixing a bug or adding a new feature.
- test: you make any testing-related changes. For example, when you write tests with Jest or any other testing framework you choose.
- chore: changes unrelated to a fix, feature, or test. For example, updating dependencies.
- docs: when you update documentation.
- style: changes that do not affect the meaning of the code, such as adding white space, missing semi-colons, etc.
- perf: changes related to performance improvements.
- build: when you make changes that affect the build files.
- ci: changes related to continuous integration.
- revert: when reverting to a previous commit.
Description
The “description” of a commit message is a concise and descriptive summary of the changes made in the commit. It serves as a headline that captures the essence of the commit.
When writing the description, keep the following in mind:
- Make it clear and specific enough to describe the commit at a glance.
- Make it brief and concise. Ideally, limiting it to 50 characters or less would be best.
- Write it in the present tense, even if you're describing changes already made.
- Make use of the imperative mood while writing it.
- Start it with a capital letter.
- Don’t end it with a period.
For example:
feat: Implement dark mode toggle for home page
This example shows how you can write the description for a commit that implements dark mode. It uses the feat type because it introduces a new feature.
Body (Optional)
The body section of a commit message provides additional details and context about the changes made in the commit. You won’t always need a body, but it can help provide more information, explain a change’s reasoning, or describe any technical considerations.
Here are some things to note while writing the body section of a commit message:
- Git never wraps text automatically, so manually wrap it at 72 characters when you write the body. This gives Git enough room to indent text, making it more readable.
- Use the body to explain what happened in the change, why you made the change, and the reasoning behind your change.
- You need to leave a blank line between the description line and the body. This allows Git to distinguish between them.
- If the commit introduces multiple changes or affects different areas of the codebase, consider using bullet points or paragraphs to break down the modifications. This improves readability and helps readers understand the different aspects of the commit.
For example:
feat: Add GitHub as an OAuth provider
Integrate GitHub as an OAuth provider to enable seamless
authentication with GitHub accounts.
- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option
The example above shows a good Git commit message for a feature that adds GitHub as an OAuth provider to your application. This commit message has a concise summary line (50 characters or less), a more detailed explanatory text (wrapped to about 72 characters), and bullet points for additional information.
Footer (Optional)
The footer section in a commit message is an optional part that provides additional information or metadata related to the commit. It is typically placed after the body section, separated by a blank line. The footer can include various types of information, such as references to related issues, tags, or special notes.
When referencing issues, pull requests, or other related items, use the appropriate syntax or format required by your project's issue-tracking system. This ensures that the references are properly recognized and linked.
For example:
feat: Add GitHub as OAuth provider
Integrate GitHub as an OAuth provider to enable seamless
authentication with GitHub accounts.
- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option
Resolves: #123
See also: #456, #789
The footer references the related issue #123 and mentions other related issues #456 and #789 for additional context.
Adding the Commit Message
You can write commit messages using the -m flag followed by the commit message enclosed in quotes (optional but recommended).
The -m flag is ideal for short commit messages, usually including the type and description.
For example:
git commit -m "chore: Change linter to ESlint"
However, when your commit message requires more detail, such as a body and a footer, you'd be better off writing the commit in a text editor or IDE.
Alternatively, you can write long commit messages in a text file and use the --file flag to specify the commit messages as the contents of the text file.
For example:
git commit --file commit_message.txt
When you run the command above, git will use the file's contents as the commit message.
You can also tell git to open your default editor to write a longer message. If you have the GIT_EDITOR or EDITOR environment variable set, git will open that program when you run a bare git commit command.
Why You Should Write Good Commit Messages
Writing good commit messages is crucial for effective collaboration and code maintenance. Clear and descriptive messages aid understanding, debugging, and code reviews. They can even contribute to project documentation or release notes.
They enable knowledge sharing, smooth onboarding, and support version control. Prioritizing quality commit messages enhances development processes and ensures codebase maintainability.