Introduction
In our last lesson, you learned the crucial pre-flight checks for any kernel contribution: validating your code against the kernel's coding style with checkpatch.pl and identifying the correct recipients with get_maintainer.pl. You now have a polished, locally committed change and know exactly who needs to see it.
The final step before sending your contribution is to package it in the precise format the kernel community's email-based workflow requires. This lesson will teach you how to generate and format a patch series using the git format-patch command.
For your goal of excelling in high-level interviews, being able to articulate this process demonstrates a practical, deep understanding of the contribution lifecycle. It shows you've moved beyond theory and into the mechanics of how code actually gets into the kernel.
The Canonical Patch Format
Before we use the tool, let's understand the "what" and "why" of the format it produces. Unlike a simple diff, a kernel patch is a specially formatted text file that acts as both an email and a self-contained change. This allows it to be processed by both humans and automated tools.
The official kernel documentation provides the definitive description of what a properly formatted patch looks like. Understanding this structure is key to appreciating what git format-patch does for you automatically.
Read section 14, 'The canonical patch format'. Pay close attention to the components it describes: the subject line structure [PATCH] subsystem: summary, the message body (your commit message), the Signed-off-by: line, the --- marker, and the diff itself. This is the target format we are about to create.
Now, let's look at a visual example. This image shows a patch file generated by git format-patch. You can clearly see the components described in the documentation you just read.
Generating Patches with git format-patch
git format-patch is the standard tool that transforms one or more of your local Git commits into the canonical patch format, creating one .patch file for each commit.
Case 1: A Single Commit
Let's start with the simplest case: generating a patch for the most recent commit on your branch (HEAD).
Write and Submit your first Linux kernel Patch
In this classic FOSDEM talk, kernel maintainer Greg Kroah-Hartman gives a live demonstration of the entire patch submission process. We'll focus on the moment he uses git format-patch.
Watch from 24:29 to 25:15. Greg runs git format-patch to create a patch for the changes he made on his tutorial branch compared to the master branch. He then opens the resulting .patch file to show its email-like structure. This is the fundamental operation.
As you saw, the command generates a file that is perfectly formatted for email submission. To generate a patch for only the latest commit, the command is straightforward:
# This creates a patch file from the most recent commit.
git format-patch -1 HEAD
This will create a file named 0001-your-commit-subject.patch in your current directory.
Case 2: A Multi-Patch Series
More complex changes should be broken down into a series of logical, sequential commits. git format-patch is designed to handle this workflow seamlessly, creating a numbered set of patch files.
Git Mailing Lists Part 1 | Ep. 16 Bits and Booze
This video from GitButler provides an excellent, detailed walkthrough of working with mailing lists. The presenters demonstrate generating a patch series from 10 separate commits.
Watch from 10:22 to 13:11. The presenter uses git format-patch on a range of commits, generating 10 separate .patch files. They then inspect the first patch file, explaining the email headers and the structure, reinforcing what you learned from the kernel documentation.
To generate a patch series from your last 3 commits, for example, you would run:
# This creates three patch files from the last three commits.
git format-patch -3 HEAD
This will generate 0001-....patch, 0002-....patch, and 0003-....patch. Notice how git automatically adds a [PATCH 1/3], [PATCH 2/3], etc., prefix to the subject line inside each file, ensuring reviewers understand the order.
The Cover Letter: Introducing Your Patch Series
When you submit a series of patches, you need a way to introduce the series as a whole—explaining the overall goal, the approach you took, and how the patches relate to each other. This is done with a cover letter.
Think of the cover letter as the equivalent of the description you would write for a Pull Request on GitHub or a Merge Request on GitLab. git format-patch can generate a template for this.
Become a Linux kernel contributor - Part 3
This article provides a clear, hands-on walkthrough of formatting a patch series, including the creation and editing of a cover letter.
Read the section '4. First walk-through: formatting and sending patches'. Focus on the git format-patch --cover-letter command. Note how it creates a special 0000-cover-letter.patch file and how the author then opens this file to edit the subject and add a description (the 'blurb').
The command to generate a two-patch series with a cover letter would be:
git format-patch --cover-letter -2 HEAD
This creates three files:
0000-cover-letter.patch: Your summary of the whole series.0001-first-commit.patch: The first logical change.0002-second-commit.patch: The second logical change.
You must open 0000-cover-letter.patch in a text editor and replace the *** SUBJECT HERE *** and *** BLURB HERE *** placeholders with a meaningful subject and a detailed description of your patch series.
Iterating with Versions (v2, v3...)
It's rare for a patch to be accepted on the first try. You will likely receive feedback and need to submit a revised version. The community convention is to version your patch series (v2, v3, etc.) to make it clear that it's an update.
git format-patch simplifies this with the -v option.
Become a Linux kernel contributor - Part 3
Let's return to the Hackerbikepacker article, which demonstrates how to create a 'v2' of a patch series after receiving feedback.
Read section '6. Second walk-through: patch versioning'. Observe the use of --subject-prefix="PATCH v2" (or the shorter -v2 flag). Pay close attention to how the author also adds a changelog section to the cover letter (under the --- marker) to explain what has changed since the previous version. This is a critical part of the process.
To generate the second version of your two-patch series, you would amend your commits with the requested fixes and then run:
# The -v2 automatically adds "[PATCH v2]" to the subject lines.
git format-patch --cover-letter -v2 -2 HEAD
Remember to also update your cover letter file to include a changelog describing the updates for v2.
Interview Scenario
An interviewer says: "You've developed a new feature for an embedded driver that involved refactoring an existing function and then adding the new capability. You've wisely split this into two separate commits. Describe the exact Git command you would use to prepare this two-patch series for submission, and explain the purpose of each file it generates."
A strong answer would be:
"I would use the git format-patch command with the --cover-letter option for the last two commits. The command would be:git format-patch --cover-letter -2 HEAD
This command generates three files:
0000-cover-letter.patch: This is the introduction to the entire series. I would edit this file to add a subject and a detailed description explaining the overall goal of the change, which is to refactor and then add the new feature.0001-refactor-fuction.patch: This is the first patch, containing the changes from my refactoring commit. The subject and body are taken directly from my first git commit message. The subject will be automatically prefixed with[PATCH 1/2].0002-add-new-feature.patch: This is the second patch, containing the changes from my feature addition commit. Its content is from my second git commit, and the subject will be prefixed with[PATCH 2/2].
This process packages my work into the standard format, making it easy for maintainers to review each logical step independently while understanding the overall context from the cover letter."
Conclusion
You have now mastered the final preparation step in the kernel contribution workflow. By using git format-patch, you can confidently convert your local commits into the universally accepted patch format that the Linux kernel community uses for review.
Key Takeaways:
git format-patchis the canonical tool for creating email-ready patch files from Git commits.- For a multi-commit change, always generate a patch series and include a
--cover-letterto provide an overview. - After receiving feedback, use the
-v<N>flag (e.g.,-v2) to generate a new, versioned series and document your changes in the cover letter.
Preview of the Next Lesson:
Your patches are committed, validated, and now perfectly formatted. The only thing left is to send them. In the final lesson of this module, we will cover the process of sending your patches with git send-email, and more importantly, how to professionally handle the feedback you receive and submit subsequent versions, closing the loop on your first contribution.