git-format-patch (1) - Linux Man Pages

git-format-patch: Prepare patches for e-mail submission


git-format-patch - Prepare patches for e-mail submission


                   [-s | --signoff]
                   [--in-reply-to=<message id>] [--suffix=.<sfx>]
                   [--rfc] [--subject-prefix=<subject prefix>]
                   [--[no-]cover-letter] [--quiet]
                   [--no-notes | --notes[=<ref>]]
                   [--range-diff=<previous> [--creation-factor=<percent>]]
                   [<common diff options>]
                   [ <since> | <revision range> ]



There are two ways to specify which commits to operate on.





If -o is specified, output files are created in <dir>. Otherwise they are created in the current working directory. The default path can be set with the format.outputDirectory configuration option. The -o option takes precedence over format.outputDirectory. To store patches in the current working directory even when format.outputDirectory points elsewhere, use -o .. All directory components will be created.





-p, --no-stat

Generate plain patches without any diffstats.




Output to a specific file instead of stdout.






Disable the indent heuristic.




Generate a diff using the "patience diff" algorithm.


Generate a diff using the "histogram diff" algorithm.


Generate a diff using the "anchored diff" algorithm.

This option may be specified more than once.



Choose a diff algorithm. The variants are as follows:

default, myers





Use "patience diff" algorithm when generating patches.



























Synonym for --dirstat=cumulative








Whether to use empty blobs as rename source.

















-D, --irreversible-delete








<orderfile> is parsed as follows:



• Each other line contains a single pattern.


-a, --text

Treat all files as text.




Ignore changes in whitespace at EOL.

-b, --ignore-space-change


-w, --ignore-all-space



Ignore changes whose lines are all blank.



-W, --function-context

Show whole surrounding functions of changes.




Disallow external diff drivers.

--textconv, --no-textconv





Show the given source prefix instead of "a/".


Show the given destination prefix instead of "b/".


Do not show any source or destination prefix.


Prepend an additional prefix to every line of output.





Prepare patches from the topmost <n> commits.

-o <dir>, --output-directory <dir>


-n, --numbered


-N, --no-numbered

Name output in [PATCH] format.

--start-number <n>

Start numbering the patches at <n> instead of 1.



-k, --keep-subject


-s, --signoff

Add Signed-off-by: line to the commit message, using the committer identity of yourself. See the signoff option in git-commit(1) for more information.






Disable the creation of an attachment, overriding the configuration setting.



--thread[=<style>], --no-thread





--in-reply-to=<message id>

Make the first mail (or all the mails with --no-thread) appear as a reply to the given <message id>, which avoids breaking threads to provide a new patch series.




Controls which parts of the cover letter will be automatically populated using the branch's description.

If <mode> is message or default, the cover letter subject will be populated with placeholder text. The body of the cover letter will be populated with the branch's description. This is the default mode when no configuration nor command line option is specified.

If <mode> is subject, the first paragraph of the branch description will populate the cover letter subject. The remainder of the description will populate the body of the cover letter.

If <mode> is auto, if the first paragraph of the branch description is greater than 100 bytes, then the mode will be message, otherwise subject will be used.

If <mode> is none, both the cover letter subject and body will be populated with placeholder text.

--subject-prefix=<subject prefix>

Instead of the standard [PATCH] prefix in the subject line, instead use [<subject prefix>]. This allows for useful naming of a patch series, and can be combined with the --numbered option.


Alias for --subject-prefix="RFC PATCH". RFC means "Request For Comments"; use this when sending an experimental patch for discussion rather than application.

-v <n>, --reroll-count=<n>

Mark the series as the <n>-th iteration of the topic. The output filenames have v<n> prepended to them, and the subject prefix ("PATCH" by default, but configurable via the --subject-prefix option) has ` v<n>` appended to it. E.g. --reroll-count=4 may produce v4-0001-add-makefile.patch file that has "Subject: [PATCH v4 1/20] Add makefile" in it.





--from, --from=<ident>

Use ident in the From: header of each commit email. If the author ident of the commit is not textually identical to the provided ident, place a From: header in the body of the message with the original author. If no ident is given, use the committer ident.

Note that this option is only useful if you are actually sending the emails and want to identify yourself as the sender, but retain the original author (and git am will correctly pick up the in-body header). Note also that git send-email already handles this transformation for you, and this option should not be used if you are feeding the result to git send-email.




In addition to the patches, generate a cover letter file containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out.


As a reviewer aid, insert an interdiff into the cover letter, or as commentary of the lone patch of a 1-patch series, showing the differences between the previous version of the patch series and the series currently being formatted. previous is a single revision naming the tip of the previous series which shares a common base with the series being formatted (for example git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2).


As a reviewer aid, insert a range-diff (see git-range-diff(1)) into the cover letter, or as commentary of the lone patch of a 1-patch series, showing the differences between the previous version of the patch series and the series currently being formatted. previous can be a single revision naming the tip of the previous series if it shares a common base with the series being formatted (for example git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2), or a revision range if the two versions of the series are disjoint (for example git format-patch --cover-letter --range-diff=feature/v1~3..feature/v1 -3 feature/v2).

Note that diff options passed to the command affect how the primary product of format-patch is generated, and they are not passed to the underlying range-diff machinery used to generate the cover-letter material (this may change in the future).


Used with --range-diff, tweak the heuristic which matches up commits between the previous and current series of patches by adjusting the creation/deletion cost fudge factor. See git-range-diff(1)) for details.

--notes[=<ref>], --no-notes



The default is --no-notes, unless the format.notes configuration is set.


Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the signature option is omitted the signature defaults to the Git version number.


Works just like --signature except the signature is read from a file.




-q, --quiet





Output an all-zero hash in each patch's From header instead of the hash of the commit.


Record the base tree information to identify the state the patch series applies to. See the BASE TREE INFORMATION section below for details. If <commit> is "auto", a base commit is automatically chosen. The --no-base option overrides a format.useAutoBase configuration.




Show progress reports on stderr as patches are generated.


You can specify extra mail header lines to be added to each message, defaults for the subject prefix and file suffix, number patches when outputting more than one patch, add "To:" or "Cc:" headers, configure attachments, change the patch output directory, and sign off patches with configuration variables.

        headers = "Organization: git-foo\n"
        subjectPrefix = CHANGE
        suffix = .txt
        numbered = auto
        to = <email>
        cc = <email>
        attach [ = mime-boundary-string ]
        signOff = true
        outputDirectory = <directory>
        coverLetter = auto
        coverFromDescription = auto



From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
From: Tony Luck <tony.luck [at]>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

arch/arm config files were slimmed down using a python script
(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)




> So we should do such-and-such.

Makes sense to me.  How about this patch?

-- >8 --
Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet

arch/arm config files were slimmed down using a python script


Checking for patch corruption


• Empty context lines that do not have any whitespace.





• Apply it:

$ git fetch <project> master:test-apply
$ git switch test-apply
$ git restore --source=HEAD --staged --worktree :/
$ git am a.patch














Approach #1 (add-on)

Install the Toggle Word Wrap add-on that is available from m[blue][] It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu that you can tick off. Now you can compose the message as you otherwise do (cut + paste, git format-patch | git imap-send, etc), but you have to insert line breaks manually in any text that you type.

Approach #2 (configuration)

Three steps:


2. Configure your general composition window to not wrap.


In Thunderbird 3: Edit..Preferences..Advanced..Config Editor. Search for "mail.wrap_long_lines". Toggle it to make sure it is set to false. Also, search for "mailnews.wraplength" and set the value to 0.



Approach #3 (external editor)

The following Thunderbird extensions are needed: AboutConfig from m[blue][] and External Editor from m[blue][]


2. Before opening a compose window, use Edit→Account Settings to uncheck the "Compose messages in HTML format" setting in the "Composition & Addressing" panel of the account to be used to send the patch.

3. In the main Thunderbird window, before you open the compose window for the patch, use Tools→about:config to set the following to the indicated values:

        mailnews.send_plaintext_flowed  => false
        mailnews.wraplength             => 0




        mail.html_compose                       => false
        mail.identity.default.compose_html      => false          => false



This should help you to submit patches inline using KMail.

1. Prepare the patch as a text file.

2. Click on New Mail.


4. Use Message → Insert file... and insert the patch.



The base tree information block is used for maintainers or third party testers to know the exact state the patch series applies to. It consists of the base commit, which is a well-known commit that is part of the stable part of the project history everybody else works off of, and zero or more prerequisite patches, which are well-known patches in flight that is not yet part of the base commit that need to be applied on top of base commit in topological order before the patches can be applied.

The base commit is shown as "base-commit: " followed by the 40-hex of the commit object name. A prerequisite patch is shown as "prerequisite-patch-id: " followed by the 40-hex patch id, which can be obtained by passing the patch through the git patch-id --stable command.

Imagine that on top of the public commit P, you applied well-known patches X, Y and Z from somebody else, and then built your three-patch series A, B, C, the history would be like:


With git format-patch --base=P -3 C (or variants thereof, e.g. with --cover-letter or using Z..C instead of -3 C to specify the range), the base tree information block is shown at the end of the first message the command outputs (either the first patch, or the cover letter), like this:

base-commit: P
prerequisite-patch-id: X
prerequisite-patch-id: Y
prerequisite-patch-id: Z

For non-linear topology, such as

    \         /

You can also use git format-patch --base=P -3 C to generate patches for A, B and C, and the identifiers for P, X, Y, Z are appended at the end of the first message.

If set --base=auto in cmdline, it will track base commit automatically, the base commit will be the merge base of tip commit of the remote-tracking branch and revision-range specified in cmdline. For a local branch, you need to track a remote branch by git branch --set-upstream-to before using this option.





$ git format-patch origin



$ git format-patch --root origin

• The same as the previous one:

$ git format-patch -M -B origin



$ git format-patch -3


Part of the git(1) suite


git-am(1), git-send-email(1)