<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="en" id="git-format-patch(1)">
<articleinfo>
    <title>git-format-patch(1)</title>
        <indexterm>
                <primary>git-format-patch(1)</primary>
        </indexterm>
</articleinfo>
<simplesect id="_name">
<title>NAME</title>
<simpara>git-format-patch - Prepare patches for e-mail submission</simpara>
</simplesect>
<simplesect id="_synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git format-patch</emphasis> [-k] [-o &lt;dir&gt; | --stdout] [--thread]
                   [--attach[=&lt;boundary&gt;] | --inline[=&lt;boundary&gt;]]
                   [-s | --signoff] [&lt;common diff options&gt;]
                   [-n | --numbered | -N | --no-numbered]
                   [--start-number &lt;n&gt;] [--numbered-files]
                   [--in-reply-to=Message-Id] [--suffix=.&lt;sfx&gt;]
                   [--ignore-if-in-upstream]
                   [--subject-prefix=Subject-Prefix]
                   [--cc=&lt;email&gt;]
                   [--cover-letter]
                   [ &lt;since&gt; | &lt;revision range&gt; ]</literallayout>
</blockquote>
</simplesect>
<simplesect id="_description">
<title>DESCRIPTION</title>
<simpara>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 <emphasis>git-am</emphasis>.</simpara>
<simpara>There are two ways to specify which commits to operate on.</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>
A single commit, &lt;since&gt;, specifies that the commits leading
   to the tip of the current branch that are not in the history
   that leads to the &lt;since&gt; to be output.
</simpara>
</listitem>
<listitem>
<simpara>
Generic &lt;revision range&gt; expression (see "SPECIFYING
   REVISIONS" section in <xref linkend="git-rev-parse(1)"/>) means the
   commits in the specified range.
</simpara>
</listitem>
</orderedlist>
<simpara>A single commit, when interpreted as a &lt;revision range&gt;
expression, means "everything that leads to that commit", but
if you write <emphasis>git format-patch &lt;commit&gt;</emphasis>, the previous rule
applies to that command line and you do not get "everything
since the beginning of the time".  If you want to format
everything since project inception to one commit, say "git
format-patch --root &lt;commit&gt;" to make it clear that it is the
latter case.  If you want to format a single commit, you can do
this with "git format-patch -1 &lt;commit&gt;".</simpara>
<simpara>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.</simpara>
<simpara>If -o is specified, output files are created in &lt;dir&gt;.  Otherwise
they are created in the current working directory.</simpara>
<simpara>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</simpara>
<simpara>If given --thread, <emphasis>git-format-patch</emphasis> 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.</simpara>
</simplesect>
<simplesect id="_options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-p
</term>
<listitem>
<simpara>
        Generate patches without diffstat.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-U&lt;n&gt;
</term>
<term>
--unified=&lt;n&gt;
</term>
<listitem>
<simpara>
        Generate diffs with &lt;n&gt; lines of context instead of
        the usual three. Implies "-p".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--raw
</term>
<listitem>
<simpara>
        Generate the raw format.
        
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--patch-with-raw
</term>
<listitem>
<simpara>
        Synonym for "-p --raw".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--patience
</term>
<listitem>
<simpara>
        Generate a diff using the "patience diff" algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--stat[=width[,name-width]]
</term>
<listitem>
<simpara>
        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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--numstat
</term>
<listitem>
<simpara>
        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 <literal>-</literal> instead of saying
        <literal>0 0</literal>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--shortstat
</term>
<listitem>
<simpara>
        Output only the last line of the --stat format containing total
        number of modified files, as well as number of added and deleted
        lines.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--dirstat[=limit]
</term>
<listitem>
<simpara>
        Output the distribution of relative amount of changes (number of lines added or
        removed) for each sub-directory. Directories with changes below
        a cut-off percent (3% by default) are not shown. The cut-off percent
        can be set with "--dirstat=limit". Changes in a child directory is not
        counted for the parent directory, unless "--cumulative" is used.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--dirstat-by-file[=limit]
</term>
<listitem>
<simpara>
        Same as --dirstat, but counts changed files instead of lines.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--summary
</term>
<listitem>
<simpara>
        Output a condensed summary of extended header information
        such as creations, renames and mode changes.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--patch-with-stat
</term>
<listitem>
<simpara>
        Synonym for "-p --stat".
         This is the default.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-z
</term>
<listitem>
<simpara>
        NUL-line termination on output.  This affects the --raw
        output field terminator.  Also output from commands such
        as "git-log" will be delimited with NUL between commits.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--name-only
</term>
<listitem>
<simpara>
        Show only names of changed files.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--name-status
</term>
<listitem>
<simpara>
        Show only names and status of changed files. See the description
        of the <literal>--diff-filter</literal> option on what the status letters mean.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--color
</term>
<listitem>
<simpara>
        Show colored diff.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-color
</term>
<listitem>
<simpara>
        Turn off colored diff, even when the configuration file
        gives the default to color output.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--color-words[=&lt;regex&gt;]
</term>
<listitem>
<simpara>
        Show colored word diff, i.e., color words which have changed.
        By default, words are separated by whitespace.
</simpara>
<simpara>When a &lt;regex&gt; is specified, every non-overlapping match of the
&lt;regex&gt; is considered a word.  Anything between these matches is
considered whitespace and ignored(!) for the purposes of finding
differences.  You may want to append <literal>|[^[:space:]]</literal> to your regular
expression to make sure that it matches all non-whitespace characters.
A match that contains a newline is silently truncated(!) at the
newline.</simpara>
<simpara>The regex can also be set via a diff driver or configuration option, see
<xref linkend="gitattributes(1)"/> or <xref linkend="git-config(1)"/>.  Giving it explicitly
overrides any diff driver or configuration setting.  Diff drivers
override configuration settings.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-renames
</term>
<listitem>
<simpara>
        Turn off rename detection, even when the configuration
        file gives the default to do so.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--check
</term>
<listitem>
<simpara>
        Warn if changes introduce trailing whitespace
        or an indent that uses a space before a tab. Exits with
        non-zero status if problems are found. Not compatible with
        --exit-code.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--full-index
</term>
<listitem>
<simpara>
        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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--binary
</term>
<listitem>
<simpara>
        In addition to --full-index, output "binary diff" that
        can be applied with "git apply".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--abbrev[=&lt;n&gt;]
</term>
<listitem>
<simpara>
        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 --full-index option above, which controls
        the diff-patch output format.  Non default number of
        digits can be specified with --abbrev=&lt;n&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-B
</term>
<listitem>
<simpara>
        Break complete rewrite changes into pairs of delete and create.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-M
</term>
<listitem>
<simpara>
        Detect renames.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-C
</term>
<listitem>
<simpara>
        Detect copies as well as renames.  See also <literal>--find-copies-harder</literal>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--diff-filter=[ACDMRTUXB*]
</term>
<listitem>
<simpara>
        Select only files that are Added (<literal>A</literal>), Copied (<literal>C</literal>),
        Deleted (<literal>D</literal>), Modified (<literal>M</literal>), Renamed (<literal>R</literal>), have their
        type (i.e. regular file, symlink, submodule, &#8230;) changed (<literal>T</literal>),
        are Unmerged (<literal>U</literal>), are
        Unknown (<literal>X</literal>), or have had their pairing Broken (<literal>B</literal>).
        Any combination of the filter characters may be used.
        When <literal>*</literal> (All-or-none) is added to the combination, all
        paths are selected if there is any file that matches
        other criteria in the comparison; if there is no file
        that matches other criteria, nothing is selected.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--find-copies-harder
</term>
<listitem>
<simpara>
        For performance reasons, by default, <literal>-C</literal> 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
        <literal>-C</literal> option has the same effect.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-l&lt;num&gt;
</term>
<listitem>
<simpara>
        -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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-S&lt;string&gt;
</term>
<listitem>
<simpara>
        Look for differences that contain the change in &lt;string&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--pickaxe-all
</term>
<listitem>
<simpara>
        When -S finds a change, show all the changes in that
        changeset, not just the files that contain the change
        in &lt;string&gt;.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--pickaxe-regex
</term>
<listitem>
<simpara>
        Make the &lt;string&gt; not a plain string but an extended POSIX
        regex to match.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-O&lt;orderfile&gt;
</term>
<listitem>
<simpara>
        Output the patch in the order specified in the
        &lt;orderfile&gt;, which has one shell glob pattern per line.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-R
</term>
<listitem>
<simpara>
        Swap two inputs; that is, show differences from index or
        on-disk file to tree contents.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--relative[=&lt;path&gt;]
</term>
<listitem>
<simpara>
        When run from a subdirectory of the project, it can be
        told to exclude changes outside the directory and show
        pathnames relative to it with this option.  When you are
        not in a subdirectory (e.g. in a bare repository), you
        can name which subdirectory to make the output relative
        to by giving a &lt;path&gt; as an argument.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-a
</term>
<term>
--text
</term>
<listitem>
<simpara>
        Treat all files as text.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--ignore-space-at-eol
</term>
<listitem>
<simpara>
        Ignore changes in whitespace at EOL.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-b
</term>
<term>
--ignore-space-change
</term>
<listitem>
<simpara>
        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 equivalent.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-w
</term>
<term>
--ignore-all-space
</term>
<listitem>
<simpara>
        Ignore whitespace when comparing lines.  This ignores
        differences even if one line has whitespace where the other
        line has none.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--inter-hunk-context=&lt;lines&gt;
</term>
<listitem>
<simpara>
        Show the context between diff hunks, up to the specified number
        of lines, thereby fusing hunks that are close to each other.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--exit-code
</term>
<listitem>
<simpara>
        Make the program exit with codes similar to diff(1).
        That is, it exits with 1 if there were differences and
        0 means no differences.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--quiet
</term>
<listitem>
<simpara>
        Disable all output of the program. Implies --exit-code.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--ext-diff
</term>
<listitem>
<simpara>
        Allow an external diff helper to be executed. If you set an
        external diff driver with <xref linkend="gitattributes(5)"/>, you need
        to use this option with <xref linkend="git-log(1)"/> and friends.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-ext-diff
</term>
<listitem>
<simpara>
        Disallow external diff drivers.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--ignore-submodules
</term>
<listitem>
<simpara>
        Ignore changes to submodules in the diff generation.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--src-prefix=&lt;prefix&gt;
</term>
<listitem>
<simpara>
        Show the given source prefix instead of "a/".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--dst-prefix=&lt;prefix&gt;
</term>
<listitem>
<simpara>
        Show the given destination prefix instead of "b/".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-prefix
</term>
<listitem>
<simpara>
        Do not show any source or destination prefix.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<simpara>For more detailed explanation on these common options, see also
<xref linkend="gitdiffcore(7)"/>.</simpara>
<variablelist>
<varlistentry>
<term>
-&lt;n&gt;
</term>
<listitem>
<simpara>
        Limits the number of patches to prepare.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o &lt;dir&gt;
</term>
<term>
--output-directory &lt;dir&gt;
</term>
<listitem>
<simpara>
        Use &lt;dir&gt; to store the resulting files, instead of the
        current working directory.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-n
</term>
<term>
--numbered
</term>
<listitem>
<simpara>
        Name output in <emphasis>[PATCH n/m]</emphasis> format, even with a single patch.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-N
</term>
<term>
--no-numbered
</term>
<listitem>
<simpara>
        Name output in <emphasis>[PATCH]</emphasis> format.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--start-number &lt;n&gt;
</term>
<listitem>
<simpara>
        Start numbering the patches at &lt;n&gt; instead of 1.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--numbered-files
</term>
<listitem>
<simpara>
        Output file names will be a simple number sequence
        without the default first line of the commit appended.
        Mutually exclusive with the --stdout option.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-k
</term>
<term>
--keep-subject
</term>
<listitem>
<simpara>
        Do not strip/add <emphasis>[PATCH]</emphasis> from the first line of the
        commit log message.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-s
</term>
<term>
--signoff
</term>
<listitem>
<simpara>
        Add <literal>Signed-off-by:</literal> line to the commit message, using
        the committer identity of yourself.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--stdout
</term>
<listitem>
<simpara>
        Print all commits to the standard output in mbox format,
        instead of creating a file for each one.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--attach[=&lt;boundary&gt;]
</term>
<listitem>
<simpara>
        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".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--inline[=&lt;boundary&gt;]
</term>
<listitem>
<simpara>
        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".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--thread
</term>
<listitem>
<simpara>
        Add In-Reply-To and References headers to make the second and
        subsequent mails appear as replies to the first.  Also generates
        the Message-Id header to reference.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--in-reply-to=Message-Id
</term>
<listitem>
<simpara>
        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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--ignore-if-in-upstream
</term>
<listitem>
<simpara>
        Do not include a patch that matches a commit in
        &lt;until&gt;..&lt;since&gt;.  This will examine all patches reachable
        from &lt;since&gt; but not from &lt;until&gt; and compare them with the
        patches being generated, and any patch that matches is
        ignored.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--subject-prefix=&lt;Subject-Prefix&gt;
</term>
<listitem>
<simpara>
        Instead of the standard <emphasis>[PATCH]</emphasis> prefix in the subject
        line, instead use <emphasis>[&lt;Subject-Prefix&gt;]</emphasis>. This
        allows for useful naming of a patch series, and can be
        combined with the --numbered option.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--cc=&lt;email&gt;
</term>
<listitem>
<simpara>
        Add a "Cc:" header to the email headers. This is in addition
        to any configured headers, and may be used multiple times.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--cover-letter
</term>
<listitem>
<simpara>
        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 out.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--suffix=.&lt;sfx&gt;
</term>
<listitem>
<simpara>
        Instead of using <literal>.patch</literal> as the suffix for generated
        filenames, use specified suffix.  A common alternative is
        <literal>--suffix=.txt</literal>.
</simpara>
<simpara>Note that you would need to include the leading dot <literal>.</literal> if you
want a filename like <literal>0001-description-of-my-change.patch</literal>, and
the first letter does not have to be a dot.  Leaving it empty would
not add any suffix.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-binary
</term>
<listitem>
<simpara>
        Don&#8217;t output contents of changes in binary files, just take note
        that they differ.  Note that this disable the patch to be properly
        applied.  By default the contents of changes in those files are
        encoded in the patch.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="_configuration">
<title>CONFIGURATION</title>
<simpara>You can specify extra mail header lines to be added to each message
in the repository configuration, new defaults for the subject prefix
and file suffix, and number patches when outputting more than one.</simpara>
<literallayout>[format]
        headers = "Organization: git-foo\n"
        subjectprefix = CHANGE
        suffix = .txt
        numbered = auto
        cc = &lt;email&gt;</literallayout>
</simplesect>
<simplesect id="_examples">
<title>EXAMPLES</title>
<itemizedlist>
<listitem>
<simpara>
Extract commits between revisions R1 and R2, and apply them on top of
the current branch using <emphasis>git-am</emphasis> to cherry-pick them:
</simpara>
<literallayout>$ git format-patch -k --stdout R1..R2 | git am -3 -k</literallayout>
</listitem>
<listitem>
<simpara>
Extract all commits which are in the current branch but not in the
origin branch:
</simpara>
<literallayout>$ git format-patch origin</literallayout>
<simpara>For each commit a separate file is created in the current directory.</simpara>
</listitem>
<listitem>
<simpara>
Extract all commits that lead to <emphasis>origin</emphasis> since the inception of the
project:
</simpara>
<literallayout>$ git format-patch --root origin</literallayout>
</listitem>
<listitem>
<simpara>
The same as the previous one:
</simpara>
<literallayout>$ git format-patch -M -B origin</literallayout>
<simpara>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 it.
Note that the "patch" program does not understand renaming patches, so
use it only when you know the recipient uses git to apply your patch.</simpara>
</listitem>
<listitem>
<simpara>
Extract three topmost commits from the current branch and format them
as e-mailable patches:
</simpara>
<literallayout>$ git format-patch -3</literallayout>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="_see_also">
<title>SEE ALSO</title>
<simpara><xref linkend="git-am(1)"/>, <xref linkend="git-send-email(1)"/></simpara>
</simplesect>
<simplesect id="_author">
<title>Author</title>
<simpara>Written by Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt;</simpara>
</simplesect>
<simplesect id="_documentation">
<title>Documentation</title>
<simpara>Documentation by Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>
</simplesect>
<simplesect id="_git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
</simplesect>
</article>
