1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
\r
4 <article lang="en" id="git-format-patch(1)">
\r
6 <title>git-format-patch(1)</title>
\r
8 <primary>git-format-patch(1)</primary>
\r
11 <simplesect id="_name">
\r
13 <simpara>git-format-patch - Prepare patches for e-mail submission</simpara>
\r
15 <simplesect id="_synopsis">
\r
16 <title>SYNOPSIS</title>
\r
18 <literallayout><emphasis>git format-patch</emphasis> [-k] [-o <dir> | --stdout] [--thread]
\r
19 [--attach[=<boundary>] | --inline[=<boundary>]]
\r
20 [-s | --signoff] [<common diff options>]
\r
21 [-n | --numbered | -N | --no-numbered]
\r
22 [--start-number <n>] [--numbered-files]
\r
23 [--in-reply-to=Message-Id] [--suffix=.<sfx>]
\r
24 [--ignore-if-in-upstream]
\r
25 [--subject-prefix=Subject-Prefix]
\r
26 [--cc=<email>]
\r
28 [ <since> | <revision range> ]</literallayout>
\r
31 <simplesect id="_description">
\r
32 <title>DESCRIPTION</title>
\r
33 <simpara>Prepare each commit with its patch in
\r
34 one file per commit, formatted to resemble UNIX mailbox format.
\r
35 The output of this command is convenient for e-mail submission or
\r
36 for use with <emphasis>git-am</emphasis>.</simpara>
\r
37 <simpara>There are two ways to specify which commits to operate on.</simpara>
\r
38 <orderedlist numeration="arabic">
\r
41 A single commit, <since>, specifies that the commits leading
\r
42 to the tip of the current branch that are not in the history
\r
43 that leads to the <since> to be output.
\r
48 Generic <revision range> expression (see "SPECIFYING
\r
49 REVISIONS" section in <xref linkend="git-rev-parse(1)"/>) means the
\r
50 commits in the specified range.
\r
54 <simpara>A single commit, when interpreted as a <revision range>
\r
55 expression, means "everything that leads to that commit", but
\r
56 if you write <emphasis>git format-patch <commit></emphasis>, the previous rule
\r
57 applies to that command line and you do not get "everything
\r
58 since the beginning of the time". If you want to format
\r
59 everything since project inception to one commit, say "git
\r
60 format-patch --root <commit>" to make it clear that it is the
\r
61 latter case. If you want to format a single commit, you can do
\r
62 this with "git format-patch -1 <commit>".</simpara>
\r
63 <simpara>By default, each output file is numbered sequentially from 1, and uses the
\r
64 first line of the commit message (massaged for pathname safety) as
\r
65 the filename. With the --numbered-files option, the output file names
\r
66 will only be numbers, without the first line of the commit appended.
\r
67 The names of the output files are printed to standard
\r
68 output, unless the --stdout option is specified.</simpara>
\r
69 <simpara>If -o is specified, output files are created in <dir>. Otherwise
\r
70 they are created in the current working directory.</simpara>
\r
71 <simpara>By default, the subject of a single patch is "[PATCH] First Line" and
\r
72 the subject when multiple patches are output is "[PATCH n/m] First
\r
73 Line". To force 1/1 to be added for a single patch, use -n. To omit
\r
74 patch numbers from the subject, use -N</simpara>
\r
75 <simpara>If given --thread, <emphasis>git-format-patch</emphasis> will generate In-Reply-To and
\r
76 References headers to make the second and subsequent patch mails appear
\r
77 as replies to the first mail; this also generates a Message-Id header to
\r
78 reference.</simpara>
\r
80 <simplesect id="_options">
\r
81 <title>OPTIONS</title>
\r
89 Generate patches without diffstat.
\r
102 Generate diffs with <n> lines of context instead of
\r
103 the usual three. Implies "-p".
\r
113 Generate the raw format.
\r
124 Synonym for "-p --raw".
\r
134 Generate a diff using the "patience diff" algorithm.
\r
140 --stat[=width[,name-width]]
\r
144 Generate a diffstat. You can override the default
\r
145 output width for 80-column terminal by "--stat=width".
\r
146 The width of the filename part can be controlled by
\r
147 giving another width to it separated by a comma.
\r
157 Similar to --stat, but shows number of added and
\r
158 deleted lines in decimal notation and pathname without
\r
159 abbreviation, to make it more machine friendly. For
\r
160 binary files, outputs two <literal>-</literal> instead of saying
\r
161 <literal>0 0</literal>.
\r
171 Output only the last line of the --stat format containing total
\r
172 number of modified files, as well as number of added and deleted
\r
183 Output the distribution of relative amount of changes (number of lines added or
\r
184 removed) for each sub-directory. Directories with changes below
\r
185 a cut-off percent (3% by default) are not shown. The cut-off percent
\r
186 can be set with "--dirstat=limit". Changes in a child directory is not
\r
187 counted for the parent directory, unless "--cumulative" is used.
\r
193 --dirstat-by-file[=limit]
\r
197 Same as --dirstat, but counts changed files instead of lines.
\r
207 Output a condensed summary of extended header information
\r
208 such as creations, renames and mode changes.
\r
218 Synonym for "-p --stat".
\r
219 This is the default.
\r
229 NUL-line termination on output. This affects the --raw
\r
230 output field terminator. Also output from commands such
\r
231 as "git-log" will be delimited with NUL between commits.
\r
241 Show only names of changed files.
\r
251 Show only names and status of changed files. See the description
\r
252 of the <literal>--diff-filter</literal> option on what the status letters mean.
\r
272 Turn off colored diff, even when the configuration file
\r
273 gives the default to color output.
\r
279 --color-words[=<regex>]
\r
283 Show colored word diff, i.e., color words which have changed.
\r
284 By default, words are separated by whitespace.
\r
286 <simpara>When a <regex> is specified, every non-overlapping match of the
\r
287 <regex> is considered a word. Anything between these matches is
\r
288 considered whitespace and ignored(!) for the purposes of finding
\r
289 differences. You may want to append <literal>|[^[:space:]]</literal> to your regular
\r
290 expression to make sure that it matches all non-whitespace characters.
\r
291 A match that contains a newline is silently truncated(!) at the
\r
293 <simpara>The regex can also be set via a diff driver or configuration option, see
\r
294 <xref linkend="gitattributes(1)"/> or <xref linkend="git-config(1)"/>. Giving it explicitly
\r
295 overrides any diff driver or configuration setting. Diff drivers
\r
296 override configuration settings.</simpara>
\r
305 Turn off rename detection, even when the configuration
\r
306 file gives the default to do so.
\r
316 Warn if changes introduce trailing whitespace
\r
317 or an indent that uses a space before a tab. Exits with
\r
318 non-zero status if problems are found. Not compatible with
\r
329 Instead of the first handful of characters, show the full
\r
330 pre- and post-image blob object names on the "index"
\r
331 line when generating patch format output.
\r
341 In addition to --full-index, output "binary diff" that
\r
342 can be applied with "git apply".
\r
348 --abbrev[=<n>]
\r
352 Instead of showing the full 40-byte hexadecimal object
\r
353 name in diff-raw format output and diff-tree header
\r
354 lines, show only a partial prefix. This is
\r
355 independent of --full-index option above, which controls
\r
356 the diff-patch output format. Non default number of
\r
357 digits can be specified with --abbrev=<n>.
\r
367 Break complete rewrite changes into pairs of delete and create.
\r
387 Detect copies as well as renames. See also <literal>--find-copies-harder</literal>.
\r
393 --diff-filter=[ACDMRTUXB*]
\r
397 Select only files that are Added (<literal>A</literal>), Copied (<literal>C</literal>),
\r
398 Deleted (<literal>D</literal>), Modified (<literal>M</literal>), Renamed (<literal>R</literal>), have their
\r
399 type (i.e. regular file, symlink, submodule, …) changed (<literal>T</literal>),
\r
400 are Unmerged (<literal>U</literal>), are
\r
401 Unknown (<literal>X</literal>), or have had their pairing Broken (<literal>B</literal>).
\r
402 Any combination of the filter characters may be used.
\r
403 When <literal>*</literal> (All-or-none) is added to the combination, all
\r
404 paths are selected if there is any file that matches
\r
405 other criteria in the comparison; if there is no file
\r
406 that matches other criteria, nothing is selected.
\r
412 --find-copies-harder
\r
416 For performance reasons, by default, <literal>-C</literal> option finds copies only
\r
417 if the original file of the copy was modified in the same
\r
418 changeset. This flag makes the command
\r
419 inspect unmodified files as candidates for the source of
\r
420 copy. This is a very expensive operation for large
\r
421 projects, so use it with caution. Giving more than one
\r
422 <literal>-C</literal> option has the same effect.
\r
432 -M and -C options require O(n^2) processing time where n
\r
433 is the number of potential rename/copy targets. This
\r
434 option prevents rename/copy detection from running if
\r
435 the number of rename/copy targets exceeds the specified
\r
446 Look for differences that contain the change in <string>.
\r
456 When -S finds a change, show all the changes in that
\r
457 changeset, not just the files that contain the change
\r
468 Make the <string> not a plain string but an extended POSIX
\r
475 -O<orderfile>
\r
479 Output the patch in the order specified in the
\r
480 <orderfile>, which has one shell glob pattern per line.
\r
490 Swap two inputs; that is, show differences from index or
\r
491 on-disk file to tree contents.
\r
497 --relative[=<path>]
\r
501 When run from a subdirectory of the project, it can be
\r
502 told to exclude changes outside the directory and show
\r
503 pathnames relative to it with this option. When you are
\r
504 not in a subdirectory (e.g. in a bare repository), you
\r
505 can name which subdirectory to make the output relative
\r
506 to by giving a <path> as an argument.
\r
519 Treat all files as text.
\r
525 --ignore-space-at-eol
\r
529 Ignore changes in whitespace at EOL.
\r
538 --ignore-space-change
\r
542 Ignore changes in amount of whitespace. This ignores whitespace
\r
543 at line end, and considers all other sequences of one or
\r
544 more whitespace characters to be equivalent.
\r
557 Ignore whitespace when comparing lines. This ignores
\r
558 differences even if one line has whitespace where the other
\r
565 --inter-hunk-context=<lines>
\r
569 Show the context between diff hunks, up to the specified number
\r
570 of lines, thereby fusing hunks that are close to each other.
\r
580 Make the program exit with codes similar to diff(1).
\r
581 That is, it exits with 1 if there were differences and
\r
582 0 means no differences.
\r
592 Disable all output of the program. Implies --exit-code.
\r
602 Allow an external diff helper to be executed. If you set an
\r
603 external diff driver with <xref linkend="gitattributes(5)"/>, you need
\r
604 to use this option with <xref linkend="git-log(1)"/> and friends.
\r
614 Disallow external diff drivers.
\r
620 --ignore-submodules
\r
624 Ignore changes to submodules in the diff generation.
\r
630 --src-prefix=<prefix>
\r
634 Show the given source prefix instead of "a/".
\r
640 --dst-prefix=<prefix>
\r
644 Show the given destination prefix instead of "b/".
\r
654 Do not show any source or destination prefix.
\r
659 <simpara>For more detailed explanation on these common options, see also
\r
660 <xref linkend="gitdiffcore(7)"/>.</simpara>
\r
668 Limits the number of patches to prepare.
\r
677 --output-directory <dir>
\r
681 Use <dir> to store the resulting files, instead of the
\r
682 current working directory.
\r
695 Name output in <emphasis>[PATCH n/m]</emphasis> format, even with a single patch.
\r
708 Name output in <emphasis>[PATCH]</emphasis> format.
\r
714 --start-number <n>
\r
718 Start numbering the patches at <n> instead of 1.
\r
728 Output file names will be a simple number sequence
\r
729 without the default first line of the commit appended.
\r
730 Mutually exclusive with the --stdout option.
\r
743 Do not strip/add <emphasis>[PATCH]</emphasis> from the first line of the
\r
744 commit log message.
\r
757 Add <literal>Signed-off-by:</literal> line to the commit message, using
\r
758 the committer identity of yourself.
\r
768 Print all commits to the standard output in mbox format,
\r
769 instead of creating a file for each one.
\r
775 --attach[=<boundary>]
\r
779 Create multipart/mixed attachment, the first part of
\r
780 which is the commit message and the patch itself in the
\r
781 second part, with "Content-Disposition: attachment".
\r
787 --inline[=<boundary>]
\r
791 Create multipart/mixed attachment, the first part of
\r
792 which is the commit message and the patch itself in the
\r
793 second part, with "Content-Disposition: inline".
\r
803 Add In-Reply-To and References headers to make the second and
\r
804 subsequent mails appear as replies to the first. Also generates
\r
805 the Message-Id header to reference.
\r
811 --in-reply-to=Message-Id
\r
815 Make the first mail (or all the mails with --no-thread) appear as a
\r
816 reply to the given Message-Id, which avoids breaking threads to
\r
817 provide a new patch series.
\r
823 --ignore-if-in-upstream
\r
827 Do not include a patch that matches a commit in
\r
828 <until>..<since>. This will examine all patches reachable
\r
829 from <since> but not from <until> and compare them with the
\r
830 patches being generated, and any patch that matches is
\r
837 --subject-prefix=<Subject-Prefix>
\r
841 Instead of the standard <emphasis>[PATCH]</emphasis> prefix in the subject
\r
842 line, instead use <emphasis>[<Subject-Prefix>]</emphasis>. This
\r
843 allows for useful naming of a patch series, and can be
\r
844 combined with the --numbered option.
\r
854 Add a "Cc:" header to the email headers. This is in addition
\r
855 to any configured headers, and may be used multiple times.
\r
865 In addition to the patches, generate a cover letter file
\r
866 containing the shortlog and the overall diffstat. You can
\r
867 fill in a description in the file before sending it out.
\r
873 --suffix=.<sfx>
\r
877 Instead of using <literal>.patch</literal> as the suffix for generated
\r
878 filenames, use specified suffix. A common alternative is
\r
879 <literal>--suffix=.txt</literal>.
\r
881 <simpara>Note that you would need to include the leading dot <literal>.</literal> if you
\r
882 want a filename like <literal>0001-description-of-my-change.patch</literal>, and
\r
883 the first letter does not have to be a dot. Leaving it empty would
\r
884 not add any suffix.</simpara>
\r
893 Don’t output contents of changes in binary files, just take note
\r
894 that they differ. Note that this disable the patch to be properly
\r
895 applied. By default the contents of changes in those files are
\r
896 encoded in the patch.
\r
902 <simplesect id="_configuration">
\r
903 <title>CONFIGURATION</title>
\r
904 <simpara>You can specify extra mail header lines to be added to each message
\r
905 in the repository configuration, new defaults for the subject prefix
\r
906 and file suffix, and number patches when outputting more than one.</simpara>
\r
907 <literallayout>[format]
\r
908 headers = "Organization: git-foo\n"
\r
909 subjectprefix = CHANGE
\r
912 cc = <email></literallayout>
\r
914 <simplesect id="_examples">
\r
915 <title>EXAMPLES</title>
\r
919 Extract commits between revisions R1 and R2, and apply them on top of
\r
920 the current branch using <emphasis>git-am</emphasis> to cherry-pick them:
\r
922 <literallayout>$ git format-patch -k --stdout R1..R2 | git am -3 -k</literallayout>
\r
926 Extract all commits which are in the current branch but not in the
\r
929 <literallayout>$ git format-patch origin</literallayout>
\r
930 <simpara>For each commit a separate file is created in the current directory.</simpara>
\r
934 Extract all commits that lead to <emphasis>origin</emphasis> since the inception of the
\r
937 <literallayout>$ git format-patch --root origin</literallayout>
\r
941 The same as the previous one:
\r
943 <literallayout>$ git format-patch -M -B origin</literallayout>
\r
944 <simpara>Additionally, it detects and handles renames and complete rewrites
\r
945 intelligently to produce a renaming patch. A renaming patch reduces
\r
946 the amount of text output, and generally makes it easier to review it.
\r
947 Note that the "patch" program does not understand renaming patches, so
\r
948 use it only when you know the recipient uses git to apply your patch.</simpara>
\r
952 Extract three topmost commits from the current branch and format them
\r
953 as e-mailable patches:
\r
955 <literallayout>$ git format-patch -3</literallayout>
\r
959 <simplesect id="_see_also">
\r
960 <title>SEE ALSO</title>
\r
961 <simpara><xref linkend="git-am(1)"/>, <xref linkend="git-send-email(1)"/></simpara>
\r
963 <simplesect id="_author">
\r
964 <title>Author</title>
\r
965 <simpara>Written by Junio C Hamano <<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>></simpara>
\r
967 <simplesect id="_documentation">
\r
968 <title>Documentation</title>
\r
969 <simpara>Documentation by Junio C Hamano and the git-list <<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>>.</simpara>
\r
971 <simplesect id="_git">
\r
973 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
\r
OSDN Git Service
