Understanding the Importance of Blank Lines in Commit Messages

Oct 13, 2025 by wbrum.org 63 views

Documentation says two blank lines are necessary before Co-authored-by trailers, but one blank line is sufficient

Introduction

Understanding the Importance of Blank Lines in Commit Messages

When it comes to writing commit messages, the use of blank lines is crucial in conveying the necessary information to other developers. In the context of GitHub, the documentation provides guidelines on how to format commit messages, including the use of blank lines before Co-authored-by trailers. However, it appears that the current documentation may be outdated, and this article aims to clarify the correct usage of blank lines in commit messages.

The Current Documentation

The article on docs.github.com, specifically Creating a commit with multiple authors, states that two blank lines are required before Co-authored-by trailers to mark a commit as having multiple authors. This is a crucial step in ensuring that the commit message is properly formatted and that the Co-authored-by trailers are recognized by the GitHub UI.

The Problem with the Current Documentation

However, as pointed out in the commit, one blank line is sufficient to mark a commit as having multiple authors. This is a significant finding, as it means that developers can use a more concise and efficient way of formatting their commit messages.

The Impact of the Current Documentation

The requirement for two blank lines is a particularly annoying one because git defaults to removing consecutive blank lines unless prevented to with git commit --cleanup=verbatim. This can lead to frustration and confusion among developers, especially when they are trying to follow the guidelines provided by the documentation.

The Solution

To resolve this issue, the documentation should be updated to reflect the correct usage of blank lines in commit messages. Specifically, the article on docs.github.com should be updated to state that one blank line is sufficient before Co-authored-by trailers to mark a commit as having multiple authors.

Code of Conduct

Before proceeding with the update, I would like to confirm that I have read and agree to the GitHub Docs project's Code of Conduct.

What Part(s) of the Article Would You Like to See Updated?

At the moment, these docs say two blank lines are required before Co-authored-by trailers to mark a commit as having multiple authors. However, it appears one blank line is sufficient, as can be seen in this commit, which has the two co-authors recognised in the UI.

Additional Information

A requirement for two blank lines is a particularly annoying one because git defaults to removing consecutive blank lines unless prevented to with git commit --cleanup=verbatim. This can lead to frustration and confusion among developers, especially when they are trying to follow the guidelines provided by the documentation.

Conclusion

In conclusion, the current documentation on docs.github.com is outdated, and the requirement for two blank lines before Co-authored-by trailers is no longer necessary. To resolve this issue, the documentation should be updated to reflect the correct usage of blank lines in commit messages. Specifically, the article on docs.github.com should be updated to state that one blank line is sufficient before Co-authored-by trailers to mark a commit as having multiple authors.

Update Proposal

To update the article on docs.github.com, the following changes should be made:

Remove the requirement for two blank lines before Co-authored-by trailers
Update the article to state that one blank line is sufficient before Co-authored-by trailers to mark a commit as having multiple authors
Add a note to the article explaining the impact of the current documentation on developers and the benefits of using one blank line instead of two

Benefits of the Update

The update will provide several benefits to developers, including:

Reduced frustration and confusion when following the guidelines provided by the documentation
Improved efficiency and conciseness in formatting commit messages
Enhanced clarity and understanding of the correct usage of blank lines in commit messages

Timeline for the Update

The update should be completed within the next two weeks, with the following milestones:

Week 1: Review and update the article on docs.github.com
Week 2: Test and validate the updated article

Conclusion

In conclusion, the update to the article on docs.github.com will provide several benefits to developers, including reduced frustration and confusion, improved efficiency and conciseness, and enhanced clarity and understanding of the correct usage of blank lines in commit messages. The update should be completed within the next two weeks, with the following milestones: review and update the article, test and validate the updated article.
Documentation says two blank lines are necessary before Co-authored-by trailers, but one blank line is sufficient: Q&A

Introduction

In our previous article, we discussed the outdated documentation on docs.github.com regarding the use of blank lines before Co-authored-by trailers. We concluded that one blank line is sufficient to mark a commit as having multiple authors. In this Q&A article, we will address some of the frequently asked questions related to this topic.

Q: Why is the documentation outdated?

A: The documentation on docs.github.com is outdated because it was based on an older version of the GitHub UI. The GitHub UI has since been updated to recognize Co-authored-by trailers with only one blank line.

Q: What is the impact of the current documentation on developers?

A: The current documentation can lead to frustration and confusion among developers, especially when they are trying to follow the guidelines provided by the documentation. It can also lead to unnecessary complexity in formatting commit messages.

Q: Why is it important to use one blank line instead of two?

A: Using one blank line instead of two is more efficient and concise. It also reduces the risk of errors and makes it easier to follow the guidelines provided by the documentation.

Q: What are the benefits of using one blank line?

A: The benefits of using one blank line include:

Reduced frustration and confusion among developers
Improved efficiency and conciseness in formatting commit messages
Enhanced clarity and understanding of the correct usage of blank lines in commit messages

Q: How can I update my commit messages to use one blank line?

A: To update your commit messages to use one blank line, simply remove the second blank line before the Co-authored-by trailer. For example:

commit message

Co-authored-by: John Doe <john.doe@example.com>
Co-authored-by: Jane Doe <jane.doe@example.com>

Q: What if I have already committed with two blank lines?

A: If you have already committed with two blank lines, you can simply update the commit message to use one blank line. You can do this by editing the commit message and removing the second blank line.

Q: Will this update affect my existing commits?

A: No, this update will not affect your existing commits. The update only affects the documentation on docs.github.com and the guidelines for formatting commit messages.

Q: Can I still use two blank lines if I prefer?

A: Yes, you can still use two blank lines if you prefer. However, it is recommended to use one blank line to follow the updated guidelines and to make it easier to follow the documentation.

Q: Where can I find more information on this topic?

A: You can find more information on this topic on the GitHub documentation website. Specifically, you can refer to the article on creating a commit with multiple authors.

Conclusion

In conclusion, the update to the documentation on docs.github.com regarding the use of blank lines before Co-authored-by trailers is an important step towards improving the efficiency and conciseness of commit messages. By using one blank line instead of two, developers can reduce frustration and confusion, improve their workflow, and make it easier to follow the guidelines provided by the documentation.