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