Inline comments inside git patches

Some projects like Linux or Git work via mailing lists. In order to make a contribution, you have to send an email containing your patch.

This is “easily” generated with git itself. The typical way of doing this is:

Prepare the set of commits (N commits) that you want to contribute
Get them in “patch” form: git format-patch -N (assuming you are on top of the branch that has these commits)
git send-email --to=<mailing@list.com> *.patch

Note that this isn’t great practice (.patch files should go into folders so that you don’t mix them up, patch series should have a cover letter, …). Proper documentation can be found in git-scm.com.

Embedding comments inside your patches

Let’s get into the important stuff. What you send via email is the actual git commit that will go into the git history if the maintainer decides to take your patch.

However, you might want to communicate extra information that shouldn’t be part of the final commit. You could reply to your own email but that doesn’t quite work… There is a solution!

When applying patches, git ignores some part of them. You can leverage this to embed comments, extra information or even questions inside your commits.

Your “default” commit will look like this:

1subject
2
3body
4
5Signed-off-By: your@email.com
6...

but you can safely introduce information that git will disregard if you insert --- inside of it like this:

 1subject
 2
 3body
 4
 5Signed-off-By: your@email.com
 6---
 7
 8Some questions you might have, links for reference, examples, ...
 9
10...

You can introduce these changes by modifying the .patch file or simply by adding it to the actual commit of your local git repository. If you choose the latter, your local commit will actually have the

1---
2
3Some questions you might have, links for reference, examples, ...

inside of it, but this part will get lost in the send email, apply patch flow. You can quickly verify this locally.

This is a very common practice, you can quickly get real-world examples by looking at a random commit fom lore.kernel.org