Writing effective git commit messages is essential for maintaining a clear and useful history in version control systems. Here are some best practices for writing commit messages:
- Use the Imperative Mood: Start your commit message with an imperative verb, as if you’re giving a command or instruction. Examples include “Add,” “Fix,” “Update,” “Remove,” “Refactor,” etc. This follows the convention used by Git itself in its autogenerated commit messages like “Merge pull request…” and “Rebase completed.”
- Be Concise: The first line of the commit message should be a concise summary of the change, ideally limited to 50 characters. It’s the headline, so it should give a clear idea about the commit’s purpose at a glance.
- Use the Body to Explain “What” and “Why”: If the change is complex and cannot be sufficiently described in one line, write a body separated from the summary by a blank line. Explain what was changed and why, but not how—the code explains the “how.” The body can be as detailed as necessary.
- Capitalize the First Letter: Begin the commit message with a capitalized letter.
- Do Not End the Summary with a Period: The summary line should be concise and to the point, so avoid ending it with a period.
- Include References to Issue Trackers if Applicable: If your project uses issue tracking, include a reference to the relevant issue or ticket at the end of the body. For example, you might write “Closes #34” or “Fixes #123.”
- Use Bullet Points in the Body: If you’re describing multiple changes in the body, consider using bullet points to make the commit message easier to read.
- Be Consistent with Language and Style: Consistency helps in understanding and maintaining the project history. If your project follows certain conventions or styles, stick to them.
Example of a Good Commit Message
Here’s an example of a well-structured commit message:
Refactor subsystem X for readability
- Split the subsystem into logical components
- Increase code reuse
- Improve the module's API readability and maintenance
Improvements were made based on the feedback from [User/Team]. This change is expected to simplify future updates to the subsystem.
See the discussion in issue #123 for more details.
This message is clear, structured, and provides both a concise summary and a detailed explanation, which is beneficial for teammates or even for you in the future when you need to understand why changes were made.