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 | -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--start-number <n>:: 81 Start numbering the patches at <n> instead of 1. 82 83--numbered-files:: 84 Output file names will be a simple number sequence 85 without the default first line of the commit appended. 86 Mutually exclusive with the --stdout option. 87 88-k|--keep-subject:: 89 Do not strip/add '[PATCH]' from the first line of the 90 commit log message. 91 92-s|--signoff:: 93 Add `Signed-off-by:` line to the commit message, using 94 the committer identity of yourself. 95 96--stdout:: 97 Print all commits to the standard output in mbox format, 98 instead of creating a file for each one. 99 100--attach[=<boundary>]:: 101 Create multipart/mixed attachment, the first part of 102 which is the commit message and the patch itself in the 103 second part, with "Content-Disposition: attachment". 104 105--inline[=<boundary>]:: 106 Create multipart/mixed attachment, the first part of 107 which is the commit message and the patch itself in the 108 second part, with "Content-Disposition: inline". 109 110--thread:: 111 Add In-Reply-To and References headers to make the second and 112 subsequent mails appear as replies to the first. Also generates 113 the Message-Id header to reference. 114 115--in-reply-to=Message-Id:: 116 Make the first mail (or all the mails with --no-thread) appear as a 117 reply to the given Message-Id, which avoids breaking threads to 118 provide a new patch series. 119 120--ignore-if-in-upstream:: 121 Do not include a patch that matches a commit in 122 <until>..<since>. This will examine all patches reachable 123 from <since> but not from <until> and compare them with the 124 patches being generated, and any patch that matches is 125 ignored. 126 127--subject-prefix=<Subject-Prefix>:: 128 Instead of the standard '[PATCH]' prefix in the subject 129 line, instead use '[<Subject-Prefix>]'. This 130 allows for useful naming of a patch series, and can be 131 combined with the --numbered option. 132 133--suffix=.<sfx>:: 134 Instead of using `.patch` as the suffix for generated 135 filenames, use specified suffix. A common alternative is 136 `--suffix=.txt`. 137+ 138Note that you would need to include the leading dot `.` if you 139want a filename like `0001-description-of-my-change.patch`, and 140the first letter does not have to be a dot. Leaving it empty would 141not add any suffix. 142 143CONFIGURATION 144------------- 145You can specify extra mail header lines to be added to each 146message in the repository configuration. You can also specify 147new defaults for the subject prefix and file suffix. 148 149------------ 150[format] 151 headers = "Organization: git-foo\n" 152 subjectprefix = CHANGE 153 suffix = .txt 154------------ 155 156 157EXAMPLES 158-------- 159 160git-format-patch -k --stdout R1..R2 | git-am -3 -k:: 161 Extract commits between revisions R1 and R2, and apply 162 them on top of the current branch using `git-am` to 163 cherry-pick them. 164 165git-format-patch origin:: 166 Extract all commits which are in the current branch but 167 not in the origin branch. For each commit a separate file 168 is created in the current directory. 169 170git-format-patch \--root origin:: 171 Extract all commits that lead to 'origin' since the 172 inception of the project. 173 174git-format-patch -M -B origin:: 175 The same as the previous one. Additionally, it detects 176 and handles renames and complete rewrites intelligently to 177 produce a renaming patch. A renaming patch reduces the 178 amount of text output, and generally makes it easier to 179 review it. Note that the "patch" program does not 180 understand renaming patches, so use it only when you know 181 the recipient uses git to apply your patch. 182 183git-format-patch -3:: 184 Extract three topmost commits from the current branch 185 and format them as e-mailable patches. 186 187See Also 188-------- 189gitlink:git-am[1], gitlink:git-send-email[1] 190 191 192Author 193------ 194Written by Junio C Hamano <junkio@cox.net> 195 196Documentation 197-------------- 198Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 199 200GIT 201--- 202Part of the gitlink:git[7] suite