Table of Contents
introduction
Most development teams sync commits directly between their local and remote repositories using git push and git pull commands. When using these commands, Git uses the SSH or HTTPS protocol to perform data transfers between the two endpoints.
However, some project managers—including large open source projects like Linux and Git itself—prefer to work via email instead. Git has a set of subcommands specifically designed for distributed collaboration via email.
For commitments to be effectively communicated by email, they should be formatted as a text entity in a standard format. git format-patch The command assists in this process.
In this article, we explain how to use the git format-patch command to prepare one or more commits for email transfer.
What is a Git patch?
A patch in Git is a textual representation of the changes in a commit, formatted so that Git can restore the commit and apply it to a branch in another repository.
Git patch format
Git creates each patch in a new file with a .patch extension in your current directory. A Git patch has the following format:
From 21e6b1b3700970fdc2382e01d6da723e51b007b5 Mon Sep 17 00:00:00 2001
From: Jacob Stopak <jacob@initialcommit.io>
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 might seem a bit complicated, but it’s actually just a way for Git to understand the following information directly from the patch itself:
- The commit ID from which the patch was derived:
From 21e6b1b3700970fdc2382e01d6da723e51b007b5 ...
- Author of the obligee and the email (sender of the email correction):
From: Jacob Stopak <jacob@initialcommit.io>
- Patch creation date:
Date: Thu, 20 Oct 2022 22:12:00 -0700
- The subject line of the email, set to
[PATCH]followed by a commitment message:
Subject: [PATCH] Update filename
- 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
--
- Git version used to create the patch:
2.38.0
When this patch is emailed to another developer, they can use Git on their side to restore the commit and apply to a branch in their repository.
What is git format-patch?
git format-patch is a Git command that automatically creates patches between each commit and its parent, for a given set of commits. These patches are designed to be easily shared via email so that the recipient can apply these commits to their repository.
How do you create a Git patch?
Creating a patch is as simple as running git format-patch <commit> in your local Git repository.
You can specify the commit by its commit ID, any branch or tag name, or a variation of Git HEAD such as HEAD^ to the previous commitment.
After running the command, you will see one or more .patch Files created in your current directory containing the patch data. The filenames 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:
0001-Update-nf-again.patch
What does format-patch do?
By default, git format-patch is enabled
One patch is created per commit based on the difference between each commit and the parent.
Note that fixes are not generated for merge commits, so ideally you should rebase your feature to a single row of history to create a clean set of fixes.
As mentioned, one .patch Generated for each commit in your patch series.
An example of git format-patch
You can format a Git patch for one commit at a time, or for multiple commits at the same time. We’ll start with patch design for multiple commits since this is a more common scenario.
Fix in git format number of commits
By default, when you turn on the device git format-patch <commit>A patch will be created for each commit starting with the one you specified with it <commit>, until you reach the current HEAD. Therefore, you will usually create more than one patch, unless you start creating in HEAD^ (aka HEAD~1), which is the commit before the currently issued HEAD.
Note that this means no patches will be created for commits before the <commit> that you have mentioned.
Alternatively, you can use --root Check instead to create revisions for all commits from the beginning or your commit history, until specified <commit>.
Specifying multiple commits with a Git version range
Another way to create multiple fixes is to specify a range of versions, as follows:
$ git format-patch <commit1>..<commit2>
This will create fixes for all liabilities in between <commit1> and <commit2>.
See the Git documentation on specifying version ranges For more examples of valid version range syntax.
Fix in git format from single commit
Now we’ll move on to designing fixes for a single commit. You can create exactly one patch for the specified commit by using -1 flag:
$ git format-patch -1 <commit>
What is the format of a Git patch?
Earlier in this post, we showed an example format for an email patch in Git. Let’s expand on that. You can think of each patch file as a message—and indeed it is meant to be emailed as a message to another developer.
This message begins with an email header that includes the fields “From:”, “Date:”, and “Subject:”. Note that the subject field contains the first line from the commit message of the corresponding commit.
After that come the remaining lines (if any) of the commit message. Our example format above does not include more lines in the commit log message.
After that, there is a 3-dash separator, which separates the commit message from the content of the patch itself.
Finally, we have the actual diffstat output, which represents the meat of the patch. This is actually the output of 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 design a patch in Git whenever you want to send one or more commits to another person by email. This can be simply to get their input or review of proposed changes to your code.
It can also be to share a commit with a project manager so that they 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. On Windows you can use dir command. Alternatively, you can see your patches listed in your File Explorer on any operating system.
Remember that if you are creating a long patch series with many patches, you may want to put them in their own subdirectory using -o option:
$ git format-patch -o <new-feature-subdirectory> <commit>
The specified subdirectory will be created if it does not already exist.
This can be useful for grouping fixes related to a specific feature so you can make sure you only ship those fixes together and not others by mistake.
How do I view a patch file?
Because Git patches are just text files with a .patch extension, you can view them with any text editor. This can be a command-line text editor like Vim or your favorite GUI editor.
git format-patch HEAD
You might notice it if you try to run git format-patch by itself or git format-patch HEADYou will not get any output and no patch will be created.
This is because there are no differences between the specified patch (HEAD) and the current commit (which is also HEAD). So you’re confused by this, just realize that you need to specify a commit earlier in the branch history.
Adding a cover letter
In addition to creating your patches, you can create a Git cover letter that you can email as an overall summary of your patch series.
The cover letter is also a .patch A file created with the default filename 0000-cover-letter.patch.
It contains the following information:
- A custom description of the patch series
- The output of git shortlog
- The full patch series diffstat
- Git version used to generate the cover letter
Below is a sample 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 <jacob@initialcommit.io>
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
Summary
In this article, we described the purpose of Git’s format patch command and explained how it works.
We learned how to format a Git patch and when to do it. We saw that a patch in Git is just a textual representation of a difference between a commit and its parent. These differences are formatted in a standard way that makes them convenient to send by email.
If you’ve never tried Git email collaboration, why not give it a try and see if it fits your team’s workflow?
next steps
If you’re interested in learning more about how Git works under the hood, check out the Git Decoding Guide for Developers, which dives into Git’s code in an accessible way. We wrote it for developers who are curious to learn how Git works at the code level. To that end, we’ve documented the first version of Git’s code and discussed it in detail.
We hope you enjoyed this post! Feel free to email me at jacob@initialcommit.io with any questions or comments.
References
- 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
