git format-patch | Create a patch in Git
Table of Contents
- What is a Git patch?
- Git patch format
- What is git format-patch?
- How to create a Git patch?
- What does format-patch do?
- git format-patch example
- Specifying multiple commits with Git revision range
- What is the format of a Git patch?
- When should I format a git patch?
- How can I see my git patch?
- How do I view a patch file?
- git format-patch HEAD
- Adding a cover letter
- Next Steps
Most development teams sync commits directly between their local and remote repositories using the
git push and
git pull commands. When using these commands, Git uses either the SSH or HTTPS protocol to perform data transfers between the two endpoints.
However, some project maintainers - including major open source projects such as Linux and Git itself - prefer to work via email instead. Git has a set of subcommands that are specifically designed for distributed collaboration via email.
For commits to be relayed effectively over email, they need to be formatted as text entities in a standardized format. The
git format-patch command assists with this process.
In this article, we explain how to use the git format-patch command to prepare one or more commits to be transferred by email.
What is a Git patch?
A patch in Git is a textual representation of the changes in a commit, formatted in a way that Git can reconstruct the commit and apply it on a branch in another repository.
Git patch format
Git creates each patch in a new file with a
.patch extension in your current directory. Git patches have the following format:
From 21e6b1b3700970fdc2382e01d6da723e51b007b5 Mon Sep 17 00:00:00 2001 From: Jacob Stopak <firstname.lastname@example.org> Date: Thu, 20 Oct 2022 22:12:00 -0700 Subject: [PATCH] Update filename --- filename | 1 + 1 file changed, 1 insertion(+) diff --git a/filename b/filename index 01a9f34..b9022e5 100644 --- a/nf +++ b/nf @@ -1,3 +1,4 @@ asdf +asdf -- 2.38.0
This may look a bit complicated, but really it is just a way for Git to understand the following information directly from the patch itself:
- The commit id that the patch was derived from:
From 21e6b1b3700970fdc2382e01d6da723e51b007b5 ...
- The commit author and email (sender of the email patch):
From: Jacob Stopak <email@example.com>
- The date the patch was generated:
Date: Thu, 20 Oct 2022 22:12:00 -0700
- The subject line of the email, which is set to
[PATCH]followed by the commit message:
Subject: [PATCH] Update filename
- A diffstat representing the changes between the commit and its parent:
--- filename | 1 + 1 file changed, 1 insertion(+) diff --git a/filename b/filename index 01a9f34..b9022e5 100644 --- a/nf +++ b/nf @@ -1,3 +1,4 @@ asdf +asdf --
- The Git version that was used to generate the patch:
When this patch is sent to another developer over email, they can use Git on their end to reconstruct the commit and apply to a branch in their repository.
What is git format-patch?
git format-patch is a Git command that automatically generates patches between each commit and it's parent, for a given set of commits. These patches are formatted such that they can easily be shared over email, so that the recipient can apply those commits to their own repository.
How to create a Git patch?
Creating a patch is a simple as running
git format-patch <commit> in your local Git repo.
You can specify the commit using it's commit id, any branch or tag name, or a variation of Git HEAD such as
HEAD^ for the previous commit.
After running the command, you'll see one or more
.patch files generated in your current directory containing the patch data. The file names are prefixed with a 4-digit number indicating their order in the patch series, followed by a hyphen-separated string created using the commit message. For the format used above, this would be:
What does format-patch do?
By default, running git format-patch
One patch is generated per commit based on the diff between each commit and its parent.
Note that patches are not generated for merge commits, so ideally you should rebase your feature into a single line of history to generate a clean set of patches.
As mentioned, one
.patch file is generated for each commit in your patch series.
git format-patch example
You can format Git patches for one commit at a time, or for multiple commits at once. We'll start with formatting patches for multiple commits since that is a more common scenario.
git-format patch multiple commits
By default, when you run the standard
git format-patch <commit>, a patch will be created for each commit starting at the one you specified with
<commit>, up until the current HEAD is reached. Therefore, you'll usually end up with more than 1 patch being created, unless you start generating at
HEAD~1), which is the commit previous to the currently checked out HEAD.
Note that this means no patches will be created for commits previous to the
<commit> that you specified.
Alternatively, you can use the
--root flag to instead create patches for all commits from beginning or your commit history, up until the specified
Specifying multiple commits with Git revision range
Another way to generate multiple patches is to specify a range of revisions, as follows:
$ git format-patch <commit1>..<commit2>
This will create patches for all commits between
See Git's documentation on specifying revision ranges for more examples of valid revision range syntax.
git-format patch from single commit
Now let's move on to formatting patches for a single commit. You can generate exactly one patch for the specified commit by using the
$ git format-patch -1 <commit>
What is the format of a Git patch?
Earlier in this post, we showed a sample format for a email patch in Git. Let's expand on that. You can think of each patch file as being a message - and it really is since it's meant to be emailed as a message to another dev.
This message starts with an email header that includes the "From:", "Date:", and "Subject:" fields. Note that the subject field contains the first line from the commit message of the corresponding commit.
Next comes the remaining lines (if there are any) of the commit message. Our example format above does not include more lines in the commit log message.
After this, there is a 3-hyphen delimiter, separating the commit message from the patch content itself.
Lastly, we have the actual diffstat output, which represents the meat of the patch. This is actually the output of the
diff -p --stat command. Feel free to check out our git diff article for more details.
When should I format a git patch?
You should format a patch in Git any time you want to send one or more commits to another person by email. This could simply be to get their input or review on your proposed code changes.
It could also be to share a commit with a project maintainer for them to integrate into their own branch.
How can I see my git patch?
You can see your patch files in your current directory by running the
ls command in Linux or MacOS. In Windows you can use the
dir command. Alternatively, you can see your patches listed in your file explorer in any operating system.
Keep in mind that if you are generating a long patch series with many patches, you may want to put them in their own subdirectory using the
$ git format-patch -o <new-feature-subdirectory> <commit>
The specified subdirectory will be created if it doesn't yet exist.
This can be useful for grouping together patches related to a specific feature, so you can make sure to only mail out those patches together and no others by accident.
How do I view a patch file?
Since Git patches are just text files with a
.patch extension, you can view them with any text editor. This could be a command-line text editor like Vim or your favorite GUI editor.
git format-patch HEAD
You might notice that if you try to run
git format-patch on its own or
git format-patch HEAD, you won't get any output and no patch will be created.
That's because there are no differences between the specified patch (HEAD) and the current commit (which is also HEAD). So you are confused by this, just realize you need to specify a commit earlier on in the branch history.
Adding a cover letter
In addition to creating your patches, you can generate a Git cover letter which you can email as an overarching summary of your patch series.
The cover letter is also a
.patch file created with filename 0000-cover-letter.patch by default.
It contains the following information:
- Custom description of the patch series
- The git shortlog output
- The full patch series diffstat
- The Git version used to generate the cover letter
Here is an example cover letter, for which you can fill in the fields with asterisks:
$ git format-patch --cover-letter HEAD~2 0000-cover-letter.patch 0001-Revert-Revert-Add-qwer.patch 0002-Revert-Add-qwer.patch $ cat 0000-cover-letter.patch From c1033c71d0a6f136dab2abeaea4eae9c200dae6d Mon Sep 17 00:00:00 2001 From: Jacob Stopak <firstname.lastname@example.org> Date: Wed, 26 Oct 2022 09:30:39 -0700 Subject: [PATCH 0/2] *** SUBJECT HERE *** *** BLURB HERE *** Jacob Stopak (2): Revert "Revert "Add qwer"" Revert "Add qwer" -- 2.38.0
In this article, we described the purpose Git's format patch command and explained how it works.
We learned how to format a Git patch and when to do so. We saw that a patch in Git is just a textual representation of a diff between a commit and its parent. These diffs are formatted in a standardized way that makes them convenient to send over email.
If you've never tried Git email collaboration, why not give it a try and see if it suits your team's workflow?
If you're interested in learning more about how Git works under the hood, check out our Decoding Git Guidebook for Developers, which dives into Git's code in an accessible way. We wrote it for curious developers to learn how Git works at the code level. To do this, we documented the first version of Git's code and discuss it in detail.
We hope you enjoyed this post! Feel free to shoot me an email at email@example.com with any questions or comments.
- Git SCM Specifying Revision Ranges - https://git-scm.com/docs/gitrevisions#_specifying_ranges
- Git SCM format-patch command - https://git-scm.com/docs/git-format-patch
Recommended product: Decoding Git Guidebook for Developers