man pages section 1: User Commands

Exit Print View

Updated: July 2014

git-format-patch (1)


git-format-patch - mail submission


git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
[--no-thread | --thread[=<style>]]
[(--attach|--inline)[=<boundary>] | --no-attach]
[-s | --signoff]
[--signature=<signature> | --no-signature]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
[--in-reply-to=Message-Id] [--suffix=.<sfx>]
[--to=<email>] [--cc=<email>]
[--cover-letter] [--quiet]
[<common diff options>]
[ <since> | <revision range> ]


Git Manual                                    GIT-FORMAT-PATCH(1)

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

     git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
                        [--no-thread | --thread[=<style>]]
                        [(--attach|--inline)[=<boundary>] | --no-attach]
                        [-s | --signoff]
                        [--signature=<signature> | --no-signature]
                        [-n | --numbered | -N | --no-numbered]
                        [--start-number <n>] [--numbered-files]
                        [--in-reply-to=Message-Id] [--suffix=.<sfx>]
                        [--to=<email>] [--cc=<email>]
                        [--cover-letter] [--quiet]
                        [<common diff options>]
                        [ <since> | <revision range> ]

     Prepare each commit with its patch in one file per commit,
     formatted to resemble UNIX mailbox format. The output of
     this command is convenient for e-mail submission or for use
     with git am.

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

      1. A single commit, <since>, specifies that the commits
         leading to the tip of the current branch that are not in
         the history that leads to the <since> to be output.

      2. Generic <revision range> expression (see "SPECIFYING
         REVISIONS" section in gitrevisions(5)) means the commits
         in the specified range.

     The first rule takes precedence in the case of a single
     <commit>. To apply the second rule, i.e., format everything
     since the beginning of history up until <commit>, use the
     --root option: git format-patch --root <commit>. If you want
     to format only <commit> itself, you can do this with git
     format-patch -1 <commit>.

     By default, each output file is numbered sequentially from
     1, and uses the first line of the commit message (massaged
     for pathname safety) as the filename. With the
     --numbered-files option, the output file names will only be
     numbers, without the first line of the commit appended. The
     names of the output files are printed to standard output,
     unless the --stdout option is specified.

     If -o is specified, output files are created in <dir>.

Git          Last change: 02/22/2012                    1

Git Manual                                    GIT-FORMAT-PATCH(1)

     Otherwise they are created in the current working directory.

     By default, the subject of a single patch is "[PATCH] First
     Line" and the subject when multiple patches are output is
     "[PATCH n/m] First Line". To force 1/1 to be added for a
     single patch, use -n. To omit patch numbers from the
     subject, use -N.

     If given --thread, git-format-patch will generate
     In-Reply-To and References headers to make the second and
     subsequent patch mails appear as replies to the first mail;
     this also generates a Message-Id header to reference.

     -p, --no-stat
         Generate plain patches without any diffstats.

     -U<n>, --unified=<n>
         Generate diffs with <n> lines of context instead of the
         usual three.

         Spend extra time to make sure the smallest possible diff
         is produced.

         Generate a diff using the "patience diff" algorithm.

         Generate a diffstat. You can override the default output
         width for 80-column terminal by --stat=<width>. The
         width of the filename part can be controlled by giving
         another width to it separated by a comma. By giving a
         third parameter <count>, you can limit the output to the
         first <count> lines, followed by ...  if there are more.

         These parameters can also be set individually with
         --stat-width=<width>, --stat-name-width=<name-width> and

         Similar to --stat, but shows number of added and deleted
         lines in decimal notation and pathname without
         abbreviation, to make it more machine friendly. For
         binary files, outputs two - instead of saying 0 0.

         Output only the last line of the --stat format
         containing total number of modified files, as well as
         number of added and deleted lines.

Git          Last change: 02/22/2012                    2

Git Manual                                    GIT-FORMAT-PATCH(1)

         Output the distribution of relative amount of changes
         for each sub-directory. The behavior of --dirstat can be
         customized by passing it a comma separated list of
         parameters. The defaults are controlled by the
         diff.dirstat configuration variable (see git-config(1)).
         The following parameters are available:

             Compute the dirstat numbers by counting the lines
             that have been removed from the source, or added to
             the destination. This ignores the amount of pure
             code movements within a file. In other words,
             rearranging lines in a file is not counted as much
             as other changes. This is the default behavior when
             no parameter is given.

             Compute the dirstat numbers by doing the regular
             line-based diff analysis, and summing the
             removed/added line counts. (For binary files, count
             64-byte chunks instead, since binary files have no
             natural concept of lines). This is a more expensive
             --dirstat behavior than the changes behavior, but it
             does count rearranged lines within a file as much as
             other changes. The resulting output is consistent
             with what you get from the other --*stat options.

             Compute the dirstat numbers by counting the number
             of files changed. Each changed file counts equally
             in the dirstat analysis. This is the computationally
             cheapest --dirstat behavior, since it does not have
             to look at the file contents at all.

             Count changes in a child directory for the parent
             directory as well. Note that when using cumulative,
             the sum of the percentages reported may exceed 100%.
             The default (non-cumulative) behavior can be
             specified with the noncumulative parameter.

             An integer parameter specifies a cut-off percent (3%
             by default). Directories contributing less than this
             percentage of the changes are not shown in the

         Example: The following will count changed files, while
         ignoring directories with less than 10% of the total
         amount of changed files, and accumulating child
         directory counts in the parent directories:

Git          Last change: 02/22/2012                    3

Git Manual                                    GIT-FORMAT-PATCH(1)


         Output a condensed summary of extended header
         information such as creations, renames and mode changes.

         Turn off rename detection, even when the configuration
         file gives the default to do so.

         Instead of the first handful of characters, show the
         full pre- and post-image blob object names on the
         "index" line when generating patch format output.

         In addition to --full-index, output a binary diff that
         can be applied with git-apply.

         Instead of showing the full 40-byte hexadecimal object
         name in diff-raw format output and diff-tree header
         lines, show only a partial prefix. This is independent
         of the --full-index option above, which controls the
         diff-patch output format. Non default number of digits
         can be specified with --abbrev=<n>.

     -B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]
         Break complete rewrite changes into pairs of delete and
         create. This serves two purposes:

         It affects the way a change that amounts to a total
         rewrite of a file not as a series of deletion and
         insertion mixed together with a very few lines that
         happen to match textually as the context, but as a
         single deletion of everything old followed by a single
         insertion of everything new, and the number m controls
         this aspect of the -B option (defaults to 60%).  -B/70%
         specifies that less than 30% of the original should
         remain in the result for git to consider it a total
         rewrite (i.e. otherwise the resulting patch will be a
         series of deletion and insertion mixed together with
         context lines).

         When used with -M, a totally-rewritten file is also
         considered as the source of a rename (usually -M only
         considers a file that disappeared as the source of a
         rename), and the number n controls this aspect of the -B
         option (defaults to 50%).  -B20% specifies that a change
         with addition and deletion compared to 20% or more of
         the file's size are eligible for being picked up as a
         possible source of a rename to another file.

Git          Last change: 02/22/2012                    4

Git Manual                                    GIT-FORMAT-PATCH(1)

     -M[<n>], --find-renames[=<n>]
         Detect renames. If n is specified, it is a threshold on
         the similarity index (i.e. amount of addition/deletions
         compared to the file's size). For example, -M90% means
         git should consider a delete/add pair to be a rename if
         more than 90% of the file hasn't changed.

     -C[<n>], --find-copies[=<n>]
         Detect copies as well as renames. See also
         --find-copies-harder. If n is specified, it has the same
         meaning as for -M<n>.

         For performance reasons, by default, -C option finds
         copies only if the original file of the copy was
         modified in the same changeset. This flag makes the
         command inspect unmodified files as candidates for the
         source of copy. This is a very expensive operation for
         large projects, so use it with caution. Giving more than
         one -C option has the same effect.

     -D, --irreversible-delete
         Omit the preimage for deletes, i.e. print only the
         header but not the diff between the preimage and
         /dev/null. The resulting patch is not meant to be
         applied with patch nor git apply; this is solely for
         people who want to just concentrate on reviewing the
         text after the change. In addition, the output obviously
         lack enough information to apply such a patch in
         reverse, even manually, hence the name of the option.

         When used together with -B, omit also the preimage in
         the deletion part of a delete/create pair.

         The -M and -C options require O(n^2) processing time
         where n is the number of potential rename/copy targets.
         This option prevents rename/copy detection from running
         if the number of rename/copy targets exceeds the
         specified number.

         Output the patch in the order specified in the
         <orderfile>, which has one shell glob pattern per line.

     -a, --text
         Treat all files as text.

         Ignore changes in whitespace at EOL.

Git          Last change: 02/22/2012                    5

Git Manual                                    GIT-FORMAT-PATCH(1)

     -b, --ignore-space-change
         Ignore changes in amount of whitespace. This ignores
         whitespace at line end, and considers all other
         sequences of one or more whitespace characters to be

     -w, --ignore-all-space
         Ignore whitespace when comparing lines. This ignores
         differences even if one line has whitespace where the
         other line has none.

         Show the context between diff hunks, up to the specified
         number of lines, thereby fusing hunks that are close to
         each other.

     -W, --function-context
         Show whole surrounding functions of changes.

         Allow an external diff helper to be executed. If you set
         an external diff driver with gitattributes(4), you need
         to use this option with git-log(1) and friends.

         Disallow external diff drivers.

     --textconv, --no-textconv
         Allow (or disallow) external text conversion filters to
         be run when comparing binary files. See gitattributes(4)
         for details. Because textconv filters are typically a
         one-way conversion, the resulting diff is suitable for
         human consumption, but cannot be applied. For this
         reason, textconv filters are enabled by default only for
         git-diff(1) and git-log(1), but not for git-format-
         patch(1) or diff plumbing commands.

         Ignore changes to submodules in the diff generation.
         <when> can be either "none", "untracked", "dirty" or
         "all", which is the default Using "none" will consider
         the submodule modified when it either contains untracked
         or modified files or its HEAD differs from the commit
         recorded in the superproject and can be used to override
         any settings of the ignore option in git-config(1) or
         gitmodules(4). When "untracked" is used submodules are
         not considered dirty when they only contain untracked
         content (but they are still scanned for modified
         content). Using "dirty" ignores all changes to the work
         tree of submodules, only changes to the commits stored
         in the superproject are shown (this was the behavior
         until 1.7.0). Using "all" hides all changes to

Git          Last change: 02/22/2012                    6

Git Manual                                    GIT-FORMAT-PATCH(1)


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

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

         Do not show any source or destination prefix.

     For more detailed explanation on these common options, see
     also gitdiffcore(5).

         Prepare patches from the topmost <n> commits.

     -o <dir>, --output-directory <dir>
         Use <dir> to store the resulting files, instead of the
         current working directory.

     -n, --numbered
         Name output in [PATCH n/m] format, even with a single

     -N, --no-numbered
         Name output in [PATCH] format.

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

         Output file names will be a simple number sequence
         without the default first line of the commit appended.

     -k, --keep-subject
         Do not strip/add [PATCH] from the first line of the
         commit log message.

     -s, --signoff
         Add Signed-off-by: line to the commit message, using the
         committer identity of yourself.

         Print all commits to the standard output in mbox format,
         instead of creating a file for each one.

         Create multipart/mixed attachment, the first part of
         which is the commit message and the patch itself in the
         second part, with Content-Disposition: attachment.

Git          Last change: 02/22/2012                    7

Git Manual                                    GIT-FORMAT-PATCH(1)

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

         Create multipart/mixed attachment, the first part of
         which is the commit message and the patch itself in the
         second part, with Content-Disposition: inline.

     --thread[=<style>], --no-thread
         Controls addition of In-Reply-To and References headers
         to make the second and subsequent mails appear as
         replies to the first. Also controls generation of the
         Message-Id header to reference.

         The optional <style> argument can be either shallow or
         deep.  shallow threading makes every mail a reply to the
         head of the series, where the head is chosen from the
         cover letter, the --in-reply-to, and the first patch
         mail, in this order.  deep threading makes every mail a
         reply to the previous one.

         The default is --no-thread, unless the format.thread
         configuration is set. If --thread is specified without a
         style, it defaults to the style specified by
         format.thread if any, or else shallow.

         Beware that the default for git send-email is to thread
         emails itself. If you want git format-patch to take care
         of threading, you will want to ensure that threading is
         disabled for git send-email.

         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.

         Do not include a patch that matches a commit in
         <until>..<since>. This will examine all patches
         reachable from <since> but not from <until> and compare
         them with the patches being generated, and any patch
         that matches is ignored.

         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.

         Add a To: header to the email headers. This is in

Git          Last change: 02/22/2012                    8

Git Manual                                    GIT-FORMAT-PATCH(1)

         addition to any configured headers, and may be used
         multiple times. The negated form --no-to discards all
         To: headers added so far (from config or command line).

         Add a Cc: header to the email headers. This is in
         addition to any configured headers, and may be used
         multiple times. The negated form --no-cc discards all
         Cc: headers added so far (from config or command line).

         Add an arbitrary header to the email headers. This is in
         addition to any configured headers, and may be used
         multiple times. For example, --add-header="Organization:
         git-foo". The negated form --no-add-header discards all
         (To:, Cc:, and custom) headers added so far from config
         or command line.

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

         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.

         Instead of using .patch as the suffix for generated
         filenames, use specified suffix. A common alternative is
         --suffix=.txt. Leaving this empty will remove the .patch

         Note that the leading character does not have to be a
         dot; for example, you can use --suffix=-patch to get

         Do not print the names of the generated files to
         standard output.

         Do not output contents of changes in binary files,
         instead display a notice that those files changed.
         Patches generated using this option cannot be applied
         properly, but they are still useful for code review.

         Treat the revision argument as a <revision range>, even

Git          Last change: 02/22/2012                    9

Git Manual                                    GIT-FORMAT-PATCH(1)

         if it is just a single commit (that would normally be
         treated as a <since>). Note that root commits included
         in the specified range are always formatted as creation
         patches, independently of this flag.

     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, 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

     The patch produced by git format-patch is in UNIX mailbox
     format, with a fixed "magic" time stamp to indicate that the
     file is output from format-patch rather than a real mailbox,
     like so:

         From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
         From: Tony Luck <>
         Date: Tue, 13 Jul 2010 11:42:54 -0700
         Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
         MIME-Version: 1.0
         Content-Type: text/plain; charset=UTF-8
         Content-Transfer-Encoding: 8bit

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

         Do the same for ia64 so we can have sleek & trim looking

     Typically it will be placed in a MUA's drafts folder, edited
     to add timely commentary that should not go in the changelog
     after the three dashes, and then sent as a message whose
     body, in our example, starts with "arch/arm config files
     were...". On the receiving end, readers can save interesting
     patches in a UNIX mailbox and apply them with git-am(1).

Git          Last change: 02/22/2012                   10

Git Manual                                    GIT-FORMAT-PATCH(1)

     When a patch is part of an ongoing discussion, the patch
     generated by git format-patch can be tweaked to take
     advantage of the git am --scissors feature. After your
     response to the discussion comes a line that consists solely
     of "-- >8 --" (scissors and perforation), followed by the
     patch with unnecessary header fields removed:

         > 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-Knig diet

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

     When sending a patch this way, most often you are sending
     your own patch, so in addition to the "From $SHA1
     $magic_timestamp" marker you should omit From: and Date:
     lines from the patch file. The patch title is likely to be
     different from the subject of the discussion the patch is in
     response to, so it is likely that you would want to keep the
     Subject: line, like the example above.

  Checking for patch corruption
     Many mailers if not set up properly will corrupt whitespace.
     Here are two common types of corruption:

     o   Empty context lines that do not have any whitespace.

     o   Non-empty context lines that have one extra whitespace
         at the beginning.

     One way to test if your MUA is set up correctly is:

     o   Send the patch to yourself, exactly the way you would,
         except with To: and Cc: lines that do not contain the
         list and maintainer address.

     o   Save that patch to a file in UNIX mailbox format. Call
         it a.patch, say.

     o   Apply it:

             $ git fetch <project> master:test-apply
             $ git checkout test-apply
             $ git reset --hard
             $ git am a.patch

Git          Last change: 02/22/2012                   11

Git Manual                                    GIT-FORMAT-PATCH(1)

     If it does not apply correctly, there can be various

     o   The patch itself does not apply cleanly. That is bad but
         does not have much to do with your MUA. You might want
         to rebase the patch with git-rebase(1) before
         regenerating it in this case.

     o   The MUA corrupted your patch; "am" would complain that
         the patch does not apply. Look in the .git/rebase-apply/
         subdirectory and see what patch file contains and check
         for the common corruption patterns mentioned above.

     o   While at it, check the info and final-commit files as
         well. If what is in final-commit is not exactly what you
         would want to see in the commit log message, it is very
         likely that the receiver would end up hand editing the
         log message when applying your patch. Things like "Hi,
         this is my first patch.\n" in the patch e-mail should
         come after the three-dash line that signals the end of
         the commit message.

     Here are some hints on how to successfully submit patches
     inline using various mailers.

     GMail does not have any way to turn off line wrapping in the
     web interface, so it will mangle any emails that you send.
     You can however use "git send-email" and send your patches
     through the GMail SMTP server, or use any IMAP email client
     to connect to the google IMAP server and forward the emails
     through that.

     For hints on using git send-email to send your patches
     through the GMail SMTP server, see the EXAMPLE section of

     For hints on submission using the IMAP interface, see the
     EXAMPLE section of git-imap-send(1).

     By default, Thunderbird will both wrap emails as well as
     flag them as being format=flowed, both of which will make
     the resulting email unusable by git.

     There are three different approaches: use an add-on to turn
     off line wraps, configure Thunderbird to not mangle patches,
     or use an external editor to keep Thunderbird from mangling
     the patches.

     Approach #1 (add-on)

Git          Last change: 02/22/2012                   12

Git Manual                                    GIT-FORMAT-PATCH(1)

         Install the Toggle Word Wrap add-on that is available
         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

     Approach #2 (configuration)

         Three steps:

          1. Configure your mail server composition as plain
             text: Edit...Account Settings...Composition &
             Addressing, uncheck "Compose Messages in HTML".

          2. Configure your general composition window to not

             In Thunderbird 2: Edit..Preferences..Composition,
             wrap plain text messages at 0

             In Thunderbird 3:
             Edit..Preferences..Advanced..Config Editor. Search
             for "mail.wrap_long_lines". Toggle it to make sure
             it is set to false.

          3. Disable the use of format=flowed:
             Edit..Preferences..Advanced..Config Editor. Search
             for "mailnews.send_plaintext_flowed". Toggle it to
             make sure it is set to false.

         After that is done, you should be able to compose email
         as you otherwise would (cut + paste, git format-patch |
         git imap-send, etc), and the patches will not be

     Approach #3 (external editor)

         The following Thunderbird extensions are needed:
         AboutConfig from and
         External Editor from

          1. Prepare the patch as a text file using your method
             of choice.

          2. Before opening a compose window, use Edit->Account
             Settings to uncheck the "Compose messages in HTML
             format" setting in the "Composition & Addressing"

Git          Last change: 02/22/2012                   13

Git Manual                                    GIT-FORMAT-PATCH(1)

             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

          4. Open a compose window and click the external editor

          5. In the external editor window, read in the patch
             file and exit the editor normally.

         Side note: it may be possible to do step 2 with
         about:config and the following settings but no one's
         tried yet.

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

         There is a script in contrib/thunderbird-patch-inline
         which can help you include patches with Thunderbird in
         an easy way. To use it, do the steps above and then use
         the script as the external editor.

     This should help you to submit patches inline using KMail.

      1. Prepare the patch as a text file.

      2. Click on New Mail.

      3. Go under "Options" in the Composer window and be sure
         that "Word wrap" is not set.

      4. Use Message -> Insert file... and insert the patch.

      5. Back in the compose window: add whatever other text you
         wish to the message, complete the addressing and subject
         fields, and press send.

     o   Extract commits between revisions R1 and R2, and apply
         them on top of the current branch using git am to
         cherry-pick them:

Git          Last change: 02/22/2012                   14

Git Manual                                    GIT-FORMAT-PATCH(1)

             $ git format-patch -k --stdout R1..R2 | git am -3 -k

     o   Extract all commits which are in the current branch but
         not in the origin branch:

             $ git format-patch origin

         For each commit a separate file is created in the
         current directory.

     o   Extract all commits that lead to origin since the
         inception of the project:

             $ git format-patch --root origin

     o   The same as the previous one:

             $ git format-patch -M -B origin

         Additionally, it detects and handles renames and
         complete rewrites intelligently to produce a renaming
         patch. A renaming patch reduces the amount of text
         output, and generally makes it easier to review. Note
         that non-git "patch" programs won't understand renaming
         patches, so use it only when you know the recipient uses
         git to apply your patch.

     o   Extract three topmost commits from the current branch
         and format them as e-mailable patches:

             $ git format-patch -3

     See attributes(5) for descriptions of the following

     |Availability   | developer/versioning/git |
     |Stability      | Uncommitted              |
     git-am(1), git-send-email(1)

     Part of the git(1) suite

Git          Last change: 02/22/2012                   15

Git Manual                                    GIT-FORMAT-PATCH(1)

     This software was built from source available at  The original
     community source was downloaded from  http://git-

     Further information about this software can be found on the
     open source community website at

Git          Last change: 02/22/2012                   16