1git-format-patch(1) 2=================== 3 4NAME 5---- 6git-format-patch - Prepare patches for e-mail submission 7 8 9SYNOPSIS 10-------- 11[verse] 12'git-format-patch' [-n | -N | -k] [-o <dir> | --stdout] [--thread] 13 [--attach[=<boundary>] | --inline[=<boundary>]] 14 [-s | --signoff] [<common diff options>] 15 [--start-number <n>] [--numbered-files] 16 [--in-reply-to=Message-Id] [--suffix=.<sfx>] 17 [--ignore-if-in-upstream] 18 [--subject-prefix=Subject-Prefix] 19 [ <since> | <revision range> ] 20 21DESCRIPTION 22----------- 23 24Prepare each commit with its patch in 25one file per commit, formatted to resemble UNIX mailbox format. 26The output of this command is convenient for e-mail submission or 27for use with gitlink:git-am[1]. 28 29There are two ways to specify which commits to operate on. 30 311. A single commit, <since>, specifies that the commits leading 32 to the tip of the current branch that are not in the history 33 that leads to the <since> to be output. 34 352. Generic <revision range> expression (see "SPECIFYING 36 REVISIONS" section in gitlink:git-rev-parse[1]) means the 37 commits in the specified range. 38 39A single commit, when interpreted as a <revision range> 40expression, means "everything that leads to that commit", but 41if you write 'git format-patch <commit>', the previous rule 42applies to that command line and you do not get "everything 43since the beginning of the time". If you want to format 44everything since project inception to one commit, say "git 45format-patch \--root <commit>" to make it clear that it is the 46latter case. 47 48By default, each output file is numbered sequentially from 1, and uses the 49first line of the commit message (massaged for pathname safety) as 50the filename. With the --numbered-files option, the output file names 51will only be numbers, without the first line of the commit appended. 52The names of the output files are printed to standard 53output, unless the --stdout option is specified. 54 55If -o is specified, output files are created in <dir>. Otherwise 56they are created in the current working directory. 57 58If -n is specified, instead of "[PATCH] Subject", the first line 59is formatted as "[PATCH n/m] Subject". 60 61If given --thread, git-format-patch will generate In-Reply-To and 62References headers to make the second and subsequent patch mails appear 63as replies to the first mail; this also generates a Message-Id header to 64reference. 65 66OPTIONS 67------- 68include::diff-options.txt[] 69 70-<n>:: 71 Limits the number of patches to prepare. 72 73-o|--output-directory <dir>:: 74 Use <dir> to store the resulting files, instead of the 75 current working directory. 76 77-n|--numbered:: 78 Name output in '[PATCH n/m]' format. 79 80-N|--no-numbered:: 81 Name output in '[PATCH]' format. 82 83--start-number <n>:: 84 Start numbering the patches at <n> instead of 1. 85 86--numbered-files:: 87 Output file names will be a simple number sequence 88 without the default first line of the commit appended. 89 Mutually exclusive with the --stdout option. 90 91-k|--keep-subject:: 92 Do not strip/add '[PATCH]' from the first line of the 93 commit log message. 94 95-s|--signoff:: 96 Add `Signed-off-by:` line to the commit message, using 97 the committer identity of yourself. 98 99--stdout:: 100 Print all commits to the standard output in mbox format, 101 instead of creating a file for each one. 102 103--attach[=<boundary>]:: 104 Create multipart/mixed attachment, the first part of 105 which is the commit message and the patch itself in the 106 second part, with "Content-Disposition: attachment". 107 108--inline[=<boundary>]:: 109 Create multipart/mixed attachment, the first part of 110 which is the commit message and the patch itself in the 111 second part, with "Content-Disposition: inline". 112 113--thread:: 114 Add In-Reply-To and References headers to make the second and 115 subsequent mails appear as replies to the first. Also generates 116 the Message-Id header to reference. 117 118--in-reply-to=Message-Id:: 119 Make the first mail (or all the mails with --no-thread) appear as a 120 reply to the given Message-Id, which avoids breaking threads to 121 provide a new patch series. 122 123--ignore-if-in-upstream:: 124 Do not include a patch that matches a commit in 125 <until>..<since>. This will examine all patches reachable 126 from <since> but not from <until> and compare them with the 127 patches being generated, and any patch that matches is 128 ignored. 129 130--subject-prefix=<Subject-Prefix>:: 131 Instead of the standard '[PATCH]' prefix in the subject 132 line, instead use '[<Subject-Prefix>]'. This 133 allows for useful naming of a patch series, and can be 134 combined with the --numbered option. 135 136--suffix=.<sfx>:: 137 Instead of using `.patch` as the suffix for generated 138 filenames, use specified suffix. A common alternative is 139 `--suffix=.txt`. 140+ 141Note that you would need to include the leading dot `.` if you 142want a filename like `0001-description-of-my-change.patch`, and 143the first letter does not have to be a dot. Leaving it empty would 144not add any suffix. 145 146CONFIGURATION 147------------- 148You can specify extra mail header lines to be added to each message 149in the repository configuration, new defaults for the subject prefix 150and file suffix, and number patches when outputting more than one. 151 152------------ 153[format] 154 headers = "Organization: git-foo\n" 155 subjectprefix = CHANGE 156 suffix = .txt 157 numbered = auto 158------------ 159 160 161EXAMPLES 162-------- 163 164git-format-patch -k --stdout R1..R2 | git-am -3 -k:: 165 Extract commits between revisions R1 and R2, and apply 166 them on top of the current branch using `git-am` to 167 cherry-pick them. 168 169git-format-patch origin:: 170 Extract all commits which are in the current branch but 171 not in the origin branch. For each commit a separate file 172 is created in the current directory. 173 174git-format-patch \--root origin:: 175 Extract all commits that lead to 'origin' since the 176 inception of the project. 177 178git-format-patch -M -B origin:: 179 The same as the previous one. Additionally, it detects 180 and handles renames and complete rewrites intelligently to 181 produce a renaming patch. A renaming patch reduces the 182 amount of text output, and generally makes it easier to 183 review it. Note that the "patch" program does not 184 understand renaming patches, so use it only when you know 185 the recipient uses git to apply your patch. 186 187git-format-patch -3:: 188 Extract three topmost commits from the current branch 189 and format them as e-mailable patches. 190 191See Also 192-------- 193gitlink:git-am[1], gitlink:git-send-email[1] 194 195 196Author 197------ 198Written by Junio C Hamano <junkio@cox.net> 199 200Documentation 201-------------- 202Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 203 204GIT 205--- 206Part of the gitlink:git[7] suite