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