How do I write a good commit message?

When working with Copia, writing a good commit message is often overlooked but is a crucial aspect of effective collaboration and code management. A well-crafted commit message provides clarity, context, and aids in project maintenance. The below points will highlight the best practices that contribute to clear and concise communication within development teams.

1. Separate subject from body by using the commit description: By starting the commit message with a descriptive line that summarizes the changes concisely, you create a clear separation between the subject and the body, improving the overall readability and organization of the commit message. This approach provides a structured format for conveying the purpose and details of the commit while maintaining a logical flow.

2. Limit the subject line to 50 characters: Keeping the subject line concise and focused enables quick comprehension of the commit's purpose. By adhering to a 50-character limit, you encourage the use of precise language and avoid ambiguity or excessive detail that should be explained in the body of the message.

3. Capitalize the subject line: Capitalizing the subject line enhances readability and gives it a distinct visual presence. It helps differentiate the subject line from the rest of the commit message and ensures consistency with typical sentence structures.

4. Do not end the subject line with a period: Omitting a period at the end of the subject line aligns with conventional commit message style. Commit messages are often considered as a title or a summary of the change, and periods are not typically used in titles.

5. Use the imperative mood in the subject line: The imperative mood sets a clear and concise tone for commit messages. Starting the subject line with a verb gives a command-like feel, making it easier to understand the purpose of the commit. For example, instead of saying "Added new feature," use "Add new feature."

6. Wrap the body at 72 characters: To maintain readability across different tools and interfaces, it is recommended to wrap the commit description at 72 characters. This prevents horizontal scrolling and ensures consistent formatting across various platforms, such as command-line interfaces and Git GUIs.

7. Use the body to explain what and why vs. how: While the subject line briefly explains the purpose of the commit, the body provides an opportunity to provide more details. Focus on explaining what changes were made and why they were necessary, rather than delving into how the changes were implemented. This approach offers valuable context to reviewers, project maintainers, and future developers who need to understand the rationale behind the changes.

Writing a good commit message is an often-overlooked skill that significantly contributes to effective collaboration and code maintenance in Git-based projects. By following the seven tips outlined above, you can enhance the clarity, readability, and long-term maintainability of your commit messages. Clear and concise commit messages facilitate better collaboration, streamline code review processes, and aid in understanding the project's history. Embracing these best practices will undoubtedly make you a more effective and valued member of any development team.

You can find more information about commits in our Documentation.