| 1 | git-format-patch(1) |
| 2 | =================== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-format-patch - Prepare patches for e-mail submission |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git format-patch [-k] [(-o|--output-directory) <dir> | --stdout] |
| 13 | [--no-thread | --thread[=<style>]] |
| 14 | [(--attach|--inline)[=<boundary>] | --no-attach] |
| 15 | [-s | --signoff] |
| 16 | [--signature=<signature> | --no-signature] |
| 17 | [--signature-file=<file>] |
| 18 | [-n | --numbered | -N | --no-numbered] |
| 19 | [--start-number <n>] [--numbered-files] |
| 20 | [--in-reply-to=<message-id>] [--suffix=.<sfx>] |
| 21 | [--ignore-if-in-upstream] [--always] |
| 22 | [--cover-from-description=<mode>] |
| 23 | [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>] |
| 24 | [(--reroll-count|-v) <n>] |
| 25 | [--to=<email>] [--cc=<email>] |
| 26 | [--[no-]cover-letter] [--quiet] |
| 27 | [--commit-list-format=<format-spec>] |
| 28 | [--[no-]encode-email-headers] |
| 29 | [--no-notes | --notes[=<ref>]] |
| 30 | [--interdiff=<previous>] |
| 31 | [--range-diff=<previous> [--creation-factor=<percent>]] |
| 32 | [--filename-max-length=<n>] |
| 33 | [--progress] |
| 34 | [<common-diff-options>] |
| 35 | [ <since> | <revision-range> ] |
| 36 | |
| 37 | DESCRIPTION |
| 38 | ----------- |
| 39 | |
| 40 | Prepare each non-merge commit with its "patch" in |
| 41 | one "message" per commit, formatted to resemble a UNIX mailbox. |
| 42 | The output of this command is convenient for e-mail submission or |
| 43 | for use with `git am`. |
| 44 | |
| 45 | A "message" generated by the command consists of three parts: |
| 46 | |
| 47 | * A brief metadata header that begins with `From <commit>` |
| 48 | with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs |
| 49 | like `file`(1) to recognize that the file is an output from this |
| 50 | command, fields that record the author identity, the author date, |
| 51 | and the title of the change (taken from the first paragraph of the |
| 52 | commit log message). |
| 53 | |
| 54 | * The second and subsequent paragraphs of the commit log message. |
| 55 | |
| 56 | * The "patch", which is the `diff -p --stat` output (see |
| 57 | linkgit:git-diff[1]) between the commit and its parent. |
| 58 | |
| 59 | The log message and the patch are separated by a line with a |
| 60 | three-dash line. |
| 61 | |
| 62 | There are two ways to specify which commits to operate on. |
| 63 | |
| 64 | 1. A single commit, _<since>_, specifies that the commits leading |
| 65 | to the tip of the current branch that are not in the history |
| 66 | that leads to the _<since>_ to be output. |
| 67 | |
| 68 | 2. Generic _<revision-range>_ expression (see 'SPECIFYING |
| 69 | REVISIONS' section in linkgit:gitrevisions[7]) means the |
| 70 | commits in the specified range. |
| 71 | |
| 72 | The first rule takes precedence in the case of a single _<commit>_. To |
| 73 | apply the second rule, i.e., format everything since the beginning of |
| 74 | history up until _<commit>_, use the `--root` option: `git format-patch |
| 75 | --root <commit>`. If you want to format only _<commit>_ itself, you |
| 76 | can do this with `git format-patch -1 <commit>`. |
| 77 | |
| 78 | By default, each output file is numbered sequentially from 1, and uses the |
| 79 | first line of the commit message (massaged for pathname safety) as |
| 80 | the filename. With the `--numbered-files` option, the output file names |
| 81 | will only be numbers, without the first line of the commit appended. |
| 82 | The names of the output files are printed to standard |
| 83 | output, unless the `--stdout` option is specified. |
| 84 | |
| 85 | If `-o` is specified, output files are created in _<dir>_. Otherwise |
| 86 | they are created in the current working directory. The default path |
| 87 | can be set with the `format.outputDirectory` configuration option. |
| 88 | The `-o` option takes precedence over `format.outputDirectory`. |
| 89 | To store patches in the current working directory even when |
| 90 | `format.outputDirectory` points elsewhere, use `-o .`. All directory |
| 91 | components will be created. |
| 92 | |
| 93 | By default, the subject of a single patch is "[PATCH] " followed by |
| 94 | the concatenation of lines from the commit message up to the first blank |
| 95 | line (see the DISCUSSION section of linkgit:git-commit[1]). |
| 96 | |
| 97 | When multiple patches are output, the subject prefix will instead be |
| 98 | "[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`. |
| 99 | To omit patch numbers from the subject, use `-N`. |
| 100 | |
| 101 | If given `--thread`, `git-format-patch` will generate `In-Reply-To` and |
| 102 | `References` headers to make the second and subsequent patch mails appear |
| 103 | as replies to the first mail; this also generates a `Message-ID` header to |
| 104 | reference. |
| 105 | |
| 106 | OPTIONS |
| 107 | ------- |
| 108 | :git-format-patch: 1 |
| 109 | include::diff-options.adoc[] |
| 110 | |
| 111 | `-<n>`:: |
| 112 | Prepare patches from the topmost _<n>_ commits. |
| 113 | |
| 114 | `-o <dir>`:: |
| 115 | `--output-directory=<dir>`:: |
| 116 | Use _<dir>_ to store the resulting files, instead of the |
| 117 | current working directory. |
| 118 | |
| 119 | `-n`:: |
| 120 | `--numbered`:: |
| 121 | Name output in '[PATCH n/m]' format, even with a single patch. |
| 122 | |
| 123 | `-N`:: |
| 124 | `--no-numbered`:: |
| 125 | Name output in '[PATCH]' format. |
| 126 | |
| 127 | `--start-number <n>`:: |
| 128 | Start numbering the patches at _<n>_ instead of 1. |
| 129 | |
| 130 | `--numbered-files`:: |
| 131 | Output file names will be a simple number sequence |
| 132 | without the default first line of the commit appended. |
| 133 | |
| 134 | `-k`:: |
| 135 | `--keep-subject`:: |
| 136 | Do not strip/add '[PATCH]' from the first line of the |
| 137 | commit log message. |
| 138 | |
| 139 | `-s`:: |
| 140 | `--signoff`:: |
| 141 | Add a `Signed-off-by` trailer to the commit message, using |
| 142 | the committer identity of yourself. |
| 143 | See the signoff option in linkgit:git-commit[1] for more information. |
| 144 | |
| 145 | `--stdout`:: |
| 146 | Print all commits to the standard output in mbox format, |
| 147 | instead of creating a file for each one. |
| 148 | |
| 149 | `--attach[=<boundary>]`:: |
| 150 | Create multipart/mixed attachment, the first part of |
| 151 | which is the commit message and the patch itself in the |
| 152 | second part, with `Content-Disposition: attachment`. |
| 153 | |
| 154 | `--no-attach`:: |
| 155 | Disable the creation of an attachment, overriding the |
| 156 | configuration setting. |
| 157 | |
| 158 | `--inline[=<boundary>]`:: |
| 159 | Create multipart/mixed attachment, the first part of |
| 160 | which is the commit message and the patch itself in the |
| 161 | second part, with `Content-Disposition: inline`. |
| 162 | |
| 163 | `--thread[=<style>]`:: |
| 164 | `--no-thread`:: |
| 165 | Control addition of `In-Reply-To` and `References` headers to |
| 166 | make the second and subsequent mails appear as replies to the |
| 167 | first. Also controls generation of the `Message-ID` header to |
| 168 | reference. |
| 169 | + |
| 170 | The optional _<style>_ argument can be either `shallow` or `deep`. |
| 171 | `shallow` threading makes every mail a reply to the head of the |
| 172 | series, where the head is chosen from the cover letter, the |
| 173 | `--in-reply-to`, and the first patch mail, in this order. `deep` |
| 174 | threading makes every mail a reply to the previous one. |
| 175 | + |
| 176 | The default is `--no-thread`, unless the `format.thread` configuration |
| 177 | is set. `--thread` without an argument is equivalent to `--thread=shallow`. |
| 178 | + |
| 179 | Beware that the default for `git send-email` is to thread emails |
| 180 | itself. If you want `git format-patch` to take care of threading, you |
| 181 | will want to ensure that threading is disabled for `git send-email`. |
| 182 | |
| 183 | `--in-reply-to=<message-id>`:: |
| 184 | Make the first mail (or all the mails with `--no-thread`) appear as a |
| 185 | reply to the given _<message-id>_, which avoids breaking threads to |
| 186 | provide a new patch series. |
| 187 | |
| 188 | `--ignore-if-in-upstream`:: |
| 189 | Do not include a patch that matches a commit in |
| 190 | _<until>_.._<since>_. This will examine all patches reachable |
| 191 | from _<since>_ but not from _<until>_ and compare them with the |
| 192 | patches being generated, and any patch that matches is |
| 193 | ignored. |
| 194 | |
| 195 | `--always`:: |
| 196 | Include patches for commits that do not introduce any change, |
| 197 | which are omitted by default. |
| 198 | |
| 199 | `--cover-from-description=<mode>`:: |
| 200 | Control which parts of the cover letter will be automatically |
| 201 | populated using the branch's description. |
| 202 | + |
| 203 | _<mode>_ can have the following values: |
| 204 | |
| 205 | `message`;; |
| 206 | `default`;; the cover letter subject will be |
| 207 | populated with placeholder text. The body of the cover letter will be |
| 208 | populated with the branch's description. This is the default mode when |
| 209 | no configuration nor command line option is specified. |
| 210 | `subject`;; the first paragraph of the branch description will |
| 211 | populate the cover letter subject. The remainder of the description will |
| 212 | populate the body of the cover letter. |
| 213 | `auto`;; if the first paragraph of the branch description |
| 214 | is greater than 100 bytes, then the mode will be `message`, otherwise |
| 215 | `subject` will be used. |
| 216 | `none`;; both the cover letter subject and body will be |
| 217 | populated with placeholder text. |
| 218 | |
| 219 | `--description-file=<file>`:: |
| 220 | Use the contents of _<file>_ instead of the branch's description |
| 221 | for generating the cover letter. |
| 222 | |
| 223 | `--subject-prefix=<subject-prefix>`:: |
| 224 | Use '[<subject-prefix>]' instead of the standard '[PATCH]' |
| 225 | prefix in the subject line. This can be used to name a patch |
| 226 | series, and can be combined with the `--numbered` option. |
| 227 | + |
| 228 | The configuration variable `format.subjectPrefix` may also be used |
| 229 | to configure a subject prefix to apply to a given repository for |
| 230 | all patches. This is often useful on mailing lists which receive |
| 231 | patches for several repositories and can be used to disambiguate |
| 232 | the patches (with a value of e.g. "PATCH my-project"). |
| 233 | |
| 234 | `--filename-max-length=<n>`:: |
| 235 | Instead of the standard 64 bytes, chomp the generated output |
| 236 | filenames at around _<n>_ bytes (too short a value will be |
| 237 | silently raised to a reasonable length). Defaults to the |
| 238 | value of the `format.filenameMaxLength` configuration |
| 239 | variable, or 64 if unconfigured. |
| 240 | |
| 241 | `--rfc[=<rfc>]`:: |
| 242 | Prepends the string _<rfc>_ (defaults to "RFC") to |
| 243 | the subject prefix. As the subject prefix defaults to |
| 244 | "PATCH", you'll get "RFC PATCH" by default. |
| 245 | + |
| 246 | RFC means "Request For Comments"; use this when sending |
| 247 | an experimental patch for discussion rather than application. |
| 248 | "--rfc=WIP" may also be a useful way to indicate that a patch |
| 249 | is not complete yet ("WIP" stands for "Work In Progress"). |
| 250 | + |
| 251 | If the convention of the receiving community for a particular extra |
| 252 | string is to have it _after_ the subject prefix, the string _<rfc>_ |
| 253 | can be prefixed with a dash ("`-`") to signal that the rest of |
| 254 | the _<rfc>_ string should be appended to the subject prefix instead, |
| 255 | e.g., `--rfc='-(WIP)'` results in "PATCH (WIP)". |
| 256 | |
| 257 | `-v <n>`:: |
| 258 | `--reroll-count=<n>`:: |
| 259 | Mark the series as the _<n>_-th iteration of the topic. The |
| 260 | output filenames have `v<n>` prepended to them, and the |
| 261 | subject prefix ("PATCH" by default, but configurable via the |
| 262 | `--subject-prefix` option) has `v<n>` appended to it. E.g. |
| 263 | `--reroll-count=4` may produce `v4-0001-add-makefile.patch` |
| 264 | file that has "Subject: [PATCH v4 1/20] Add makefile" in it. |
| 265 | _<n>_ does not have to be an integer (e.g. `--reroll-count=4.4`, |
| 266 | or `--reroll-count=4rev2` are allowed), but the downside of |
| 267 | using such a reroll-count is that the range-diff/interdiff |
| 268 | with the previous version does not state exactly which |
| 269 | version the new iteration is compared against. |
| 270 | |
| 271 | `--to=<email>`:: |
| 272 | Add a `To:` header to the email headers. This is in addition |
| 273 | to any configured headers, and may be used multiple times. |
| 274 | The negated form `--no-to` discards all `To:` headers added so |
| 275 | far (from config or command line). |
| 276 | |
| 277 | `--cc=<email>`:: |
| 278 | Add a `Cc:` header to the email headers. This is in addition |
| 279 | to any configured headers, and may be used multiple times. |
| 280 | The negated form `--no-cc` discards all `Cc:` headers added so |
| 281 | far (from config or command line). |
| 282 | |
| 283 | `--from`:: |
| 284 | `--from=<ident>`:: |
| 285 | Use _<ident>_ in the `From:` header of each email. In case of a |
| 286 | commit email, if the author ident of the commit is not textually |
| 287 | identical to the provided _<ident>_, place a `From:` header in the |
| 288 | body of the message with the original author. If no _<ident>_ is |
| 289 | given, or if the option is not passed at all, use the ident of |
| 290 | the current committer. |
| 291 | + |
| 292 | Note that this option is only useful if you are actually sending the |
| 293 | emails and want to identify yourself as the sender, but retain the |
| 294 | original author (and `git am` will correctly pick up the in-body |
| 295 | header). Note also that `git send-email` already handles this |
| 296 | transformation for you, and this option should not be used if you are |
| 297 | feeding the result to `git send-email`. |
| 298 | |
| 299 | `--force-in-body-from`:: |
| 300 | `--no-force-in-body-from`:: |
| 301 | With the e-mail sender specified via the `--from` option, by |
| 302 | default, an in-body "From:" to identify the real author of |
| 303 | the commit is added at the top of the commit log message if |
| 304 | the sender is different from the author. With this option, |
| 305 | the in-body "From:" is added even when the sender and the |
| 306 | author have the same name and address, which may help if the |
| 307 | mailing list software mangles the sender's identity. |
| 308 | Defaults to the value of the `format.forceInBodyFrom` |
| 309 | configuration variable. |
| 310 | |
| 311 | `--add-header=<header>`:: |
| 312 | Add an arbitrary header to the email headers. This is in addition |
| 313 | to any configured headers, and may be used multiple times. |
| 314 | For example, `--add-header="Organization: git-foo"`. |
| 315 | The negated form `--no-add-header` discards *all* (`To:`, |
| 316 | `Cc:`, and custom) headers added so far from config or command |
| 317 | line. |
| 318 | |
| 319 | `--cover-letter`:: |
| 320 | `--no-cover-letter`:: |
| 321 | In addition to the patches, generate a cover letter file containing the |
| 322 | branch description, commit list and the overall diffstat. You can fill |
| 323 | in a description in the file before sending it out. |
| 324 | |
| 325 | `--commit-list-format=<format-spec>`:: |
| 326 | Specify the format in which to generate the commit list of the patch |
| 327 | series. The accepted values for format-spec are `shortlog`, `modern` or |
| 328 | a format-string prefixed with `log:`. E.g. `log: %s (%an)`. |
| 329 | `modern` is the same as `log:%w(72)[%(count)/%(total)] %s`. |
| 330 | The `log:` prefix can be omitted if the format-string has a `%` in it |
| 331 | (expecting that it is part of `%<placeholder>`). |
| 332 | Defaults to the `format.commitListFormat` configuration variable, if |
| 333 | set, or `shortlog`. |
| 334 | This option given from the command-line implies the use of |
| 335 | `--cover-letter` unless `--no-cover-letter` is given. |
| 336 | |
| 337 | `--encode-email-headers`:: |
| 338 | `--no-encode-email-headers`:: |
| 339 | Encode email headers that have non-ASCII characters with |
| 340 | "Q-encoding" (described in RFC 2047), instead of outputting the |
| 341 | headers verbatim. Defaults to the value of the |
| 342 | `format.encodeEmailHeaders` configuration variable. |
| 343 | |
| 344 | `--interdiff=<previous>`:: |
| 345 | As a reviewer aid, insert an interdiff into the cover letter, |
| 346 | or as commentary of the lone patch of a 1-patch series, showing |
| 347 | the differences between the previous version of the patch series and |
| 348 | the series currently being formatted. _<previous>_ is a single revision |
| 349 | naming the tip of the previous series which shares a common base with |
| 350 | the series being formatted (for example `git format-patch |
| 351 | --cover-letter --interdiff=feature/v1 -3 feature/v2`). |
| 352 | |
| 353 | `--range-diff=<previous>`:: |
| 354 | As a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1]) |
| 355 | into the cover letter, or as commentary of the lone patch of a |
| 356 | 1-patch series, showing the differences between the previous |
| 357 | version of the patch series and the series currently being formatted. |
| 358 | _<previous>_ can be a single revision naming the tip of the previous |
| 359 | series if it shares a common base with the series being formatted (for |
| 360 | example `git format-patch --cover-letter --range-diff=feature/v1 -3 |
| 361 | feature/v2`), or a revision range if the two versions of the series are |
| 362 | disjoint (for example `git format-patch --cover-letter |
| 363 | --range-diff=feature/v1~3..feature/v1 -3 feature/v2`). |
| 364 | + |
| 365 | Note that diff options passed to the command affect how the primary |
| 366 | product of `format-patch` is generated, and they are not passed to |
| 367 | the underlying `range-diff` machinery used to generate the cover-letter |
| 368 | material (this may change in the future). |
| 369 | |
| 370 | `--creation-factor=<percent>`:: |
| 371 | Used with `--range-diff`, tweak the heuristic which matches up commits |
| 372 | between the previous and current series of patches by adjusting the |
| 373 | creation/deletion cost fudge factor. See linkgit:git-range-diff[1]) |
| 374 | for details. |
| 375 | + |
| 376 | Defaults to 999 (the linkgit:git-range-diff[1] uses 60), as the use |
| 377 | case is to show comparison with an older iteration of the same |
| 378 | topic and the tool should find more correspondence between the two |
| 379 | sets of patches. |
| 380 | |
| 381 | `--notes[=<ref>]`:: |
| 382 | `--no-notes`:: |
| 383 | Append the notes (see linkgit:git-notes[1]) for the commit |
| 384 | after the three-dash line. |
| 385 | + |
| 386 | The expected use case of this is to write supporting explanation for |
| 387 | the commit that does not belong to the commit log message proper, |
| 388 | and include it with the patch submission. While one can simply write |
| 389 | these explanations after `format-patch` has run but before sending, |
| 390 | keeping them as Git notes allows them to be maintained between versions |
| 391 | of the patch series (but see the discussion of the `notes.rewrite` |
| 392 | configuration options in linkgit:git-notes[1] to use this workflow). |
| 393 | + |
| 394 | The default is `--no-notes`, unless the `format.notes` configuration is |
| 395 | set. |
| 396 | |
| 397 | `--signature=<signature>`:: |
| 398 | `--no-signature`:: |
| 399 | Add a signature to each message produced. Per RFC 3676 the signature |
| 400 | is separated from the body by a line with "-- " on it. If the |
| 401 | signature option is omitted the signature defaults to the Git version |
| 402 | number. |
| 403 | |
| 404 | `--signature-file=<file>`:: |
| 405 | Works just like `--signature` except the signature is read from a file. |
| 406 | |
| 407 | `--suffix=.<sfx>`:: |
| 408 | Instead of using `.patch` as the suffix for generated |
| 409 | filenames, use specified suffix. A common alternative is |
| 410 | `--suffix=.txt`. Leaving this empty will remove the `.patch` |
| 411 | suffix. |
| 412 | + |
| 413 | Note that the leading character does not have to be a dot; for example, |
| 414 | you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. |
| 415 | |
| 416 | `-q`:: |
| 417 | `--quiet`:: |
| 418 | Do not print the names of the generated files to standard output. |
| 419 | |
| 420 | `--no-binary`:: |
| 421 | Do not output contents of changes in binary files, instead |
| 422 | display a notice that those files changed. Patches generated |
| 423 | using this option cannot be applied properly, but they are |
| 424 | still useful for code review. |
| 425 | |
| 426 | `--zero-commit`:: |
| 427 | Output an all-zero hash in each patch's From header instead |
| 428 | of the hash of the commit. |
| 429 | |
| 430 | `--no-base`:: |
| 431 | `--base[=<commit>]`:: |
| 432 | Record the base tree information to identify the state the |
| 433 | patch series applies to. See the BASE TREE INFORMATION section |
| 434 | below for details. If _<commit>_ is `auto`, a base commit is |
| 435 | automatically chosen. The `--no-base` option overrides a |
| 436 | `format.useAutoBase` configuration. |
| 437 | |
| 438 | `--root`:: |
| 439 | Treat the revision argument as a _<revision-range>_, even if it |
| 440 | is just a single commit (that would normally be treated as a |
| 441 | _<since>_). Note that root commits included in the specified |
| 442 | range are always formatted as creation patches, independently |
| 443 | of this flag. |
| 444 | |
| 445 | `--progress`:: |
| 446 | Show progress reports on stderr as patches are generated. |
| 447 | |
| 448 | CONFIGURATION |
| 449 | ------------- |
| 450 | You can specify extra mail header lines to be added to each message, |
| 451 | defaults for the subject prefix and file suffix, number patches when |
| 452 | outputting more than one patch, add "To:" or "Cc:" headers, configure |
| 453 | attachments, change the patch output directory, and sign off patches |
| 454 | with configuration variables. |
| 455 | |
| 456 | ---- |
| 457 | [format] |
| 458 | headers = "Organization: git-foo\n" |
| 459 | subjectPrefix = CHANGE |
| 460 | suffix = .txt |
| 461 | numbered = auto |
| 462 | to = <email> |
| 463 | cc = <email> |
| 464 | attach [ = mime-boundary-string ] |
| 465 | signOff = true |
| 466 | outputDirectory = <directory> |
| 467 | coverLetter = auto |
| 468 | commitListFormat = shortlog |
| 469 | coverFromDescription = auto |
| 470 | ---- |
| 471 | |
| 472 | DISCUSSION |
| 473 | ---------- |
| 474 | |
| 475 | The patch produced by `git format-patch` is in UNIX mailbox format, |
| 476 | with a fixed "magic" time stamp to indicate that the file is output |
| 477 | from format-patch rather than a real mailbox, like so: |
| 478 | |
| 479 | ---- |
| 480 | From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 |
| 481 | From: Tony Luck <tony.luck@intel.com> |
| 482 | Date: Tue, 13 Jul 2010 11:42:54 -0700 |
| 483 | Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= |
| 484 | =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= |
| 485 | MIME-Version: 1.0 |
| 486 | Content-Type: text/plain; charset=UTF-8 |
| 487 | Content-Transfer-Encoding: 8bit |
| 488 | |
| 489 | arch/arm config files were slimmed down using a python script |
| 490 | (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment) |
| 491 | |
| 492 | Do the same for ia64 so we can have sleek & trim looking |
| 493 | ... |
| 494 | ---- |
| 495 | |
| 496 | Typically it will be placed in a MUA's drafts folder, edited to add |
| 497 | timely commentary that should not go in the changelog after the three |
| 498 | dashes, and then sent as a message whose body, in our example, starts |
| 499 | with "arch/arm config files were...". On the receiving end, readers |
| 500 | can save interesting patches in a UNIX mailbox and apply them with |
| 501 | linkgit:git-am[1]. |
| 502 | |
| 503 | When a patch is part of an ongoing discussion, the patch generated by |
| 504 | `git format-patch` can be tweaked to take advantage of the `git am |
| 505 | --scissors` feature. After your response to the discussion comes a |
| 506 | line that consists solely of "`-- >8 --`" (scissors and perforation), |
| 507 | followed by the patch with unnecessary header fields removed: |
| 508 | |
| 509 | ---- |
| 510 | ... |
| 511 | > So we should do such-and-such. |
| 512 | |
| 513 | Makes sense to me. How about this patch? |
| 514 | |
| 515 | -- >8 -- |
| 516 | Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet |
| 517 | |
| 518 | arch/arm config files were slimmed down using a python script |
| 519 | ... |
| 520 | ---- |
| 521 | |
| 522 | When sending a patch this way, most often you are sending your own |
| 523 | patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you |
| 524 | should omit `From:` and `Date:` lines from the patch file. The patch |
| 525 | title is likely to be different from the subject of the discussion the |
| 526 | patch is in response to, so it is likely that you would want to keep |
| 527 | the Subject: line, like the example above. |
| 528 | |
| 529 | Checking for patch corruption |
| 530 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 531 | Many mailers if not set up properly will corrupt whitespace. Here are |
| 532 | two common types of corruption: |
| 533 | |
| 534 | * Empty context lines that do not have _any_ whitespace. |
| 535 | |
| 536 | * Non-empty context lines that have one extra whitespace at the |
| 537 | beginning. |
| 538 | |
| 539 | One way to test if your MUA is set up correctly is: |
| 540 | |
| 541 | * Send the patch to yourself, exactly the way you would, except |
| 542 | with `To:` and `Cc:` lines that do not contain the list and |
| 543 | maintainer address. |
| 544 | |
| 545 | * Save that patch to a file in UNIX mailbox format. Call it a.patch, |
| 546 | say. |
| 547 | |
| 548 | * Apply it: |
| 549 | |
| 550 | $ git fetch <project> master:test-apply |
| 551 | $ git switch test-apply |
| 552 | $ git restore --source=HEAD --staged --worktree :/ |
| 553 | $ git am a.patch |
| 554 | |
| 555 | If it does not apply correctly, there can be various reasons. |
| 556 | |
| 557 | * The patch itself does not apply cleanly. That is _bad_ but |
| 558 | does not have much to do with your MUA. You might want to rebase |
| 559 | the patch with linkgit:git-rebase[1] before regenerating it in |
| 560 | this case. |
| 561 | |
| 562 | * The MUA corrupted your patch; "am" would complain that |
| 563 | the patch does not apply. Look in the `.git/rebase-apply/` subdirectory and |
| 564 | see what `patch` file contains and check for the common |
| 565 | corruption patterns mentioned above. |
| 566 | |
| 567 | * While at it, check the `info` and `final-commit` files as well. |
| 568 | If what is in `final-commit` is not exactly what you would want to |
| 569 | see in the commit log message, it is very likely that the |
| 570 | receiver would end up hand editing the log message when applying |
| 571 | your patch. Things like "Hi, this is my first patch.\n" in the |
| 572 | patch e-mail should come after the three-dash line that signals |
| 573 | the end of the commit message. |
| 574 | |
| 575 | MUA-SPECIFIC HINTS |
| 576 | ------------------ |
| 577 | Here are some hints on how to successfully submit patches inline using |
| 578 | various mailers. |
| 579 | |
| 580 | GMail |
| 581 | ~~~~~ |
| 582 | GMail does not have any way to turn off line wrapping in the web |
| 583 | interface, so it will mangle any emails that you send. You can however |
| 584 | use `git send-email` and send your patches through the GMail SMTP server, or |
| 585 | use any IMAP email client to connect to the google IMAP server and forward |
| 586 | the emails through that. |
| 587 | |
| 588 | For hints on using `git send-email` to send your patches through the |
| 589 | GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. |
| 590 | |
| 591 | For hints on submission using the IMAP interface, see the EXAMPLE |
| 592 | section of linkgit:git-imap-send[1]. |
| 593 | |
| 594 | Thunderbird |
| 595 | ~~~~~~~~~~~ |
| 596 | By default, Thunderbird will both wrap emails as well as flag |
| 597 | them as being `format=flowed`, both of which will make the |
| 598 | resulting email unusable by Git. |
| 599 | |
| 600 | There are three different approaches: use an add-on to turn off line wraps, |
| 601 | configure Thunderbird to not mangle patches, or use |
| 602 | an external editor to keep Thunderbird from mangling the patches. |
| 603 | |
| 604 | Approach #1 (add-on) |
| 605 | ^^^^^^^^^^^^^^^^^^^^ |
| 606 | |
| 607 | Install the Toggle Line Wrap add-on that is available from |
| 608 | https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap |
| 609 | It adds a button "Line Wrap" to the composer's toolbar |
| 610 | that you can tick off. Now you can compose the message as you otherwise do |
| 611 | (cut + paste, `git format-patch` | `git imap-send`, etc), but you have to |
| 612 | insert line breaks manually in any text that you type. |
| 613 | |
| 614 | As a bonus feature, the add-on can detect patch text in the composer |
| 615 | and warns when line wrapping has not yet been turned off. |
| 616 | |
| 617 | The add-on requires a few tweaks of the advanced configuration |
| 618 | (`about:config`). These are listed on the download page. |
| 619 | |
| 620 | Approach #2 (configuration) |
| 621 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 622 | Three steps: |
| 623 | |
| 624 | 1. Configure your mail server composition as plain text: |
| 625 | Edit...Account Settings...Composition & Addressing, |
| 626 | uncheck "Compose Messages in HTML". |
| 627 | |
| 628 | 2. Configure your general composition window to not wrap. |
| 629 | + |
| 630 | In Thunderbird 2: |
| 631 | Edit..Preferences..Composition, wrap plain text messages at 0 |
| 632 | + |
| 633 | In Thunderbird 3: |
| 634 | Edit..Preferences..Advanced..Config Editor. Search for |
| 635 | "mail.wrap_long_lines". |
| 636 | Toggle it to make sure it is set to `false`. Also, search for |
| 637 | "mailnews.wraplength" and set the value to 0. |
| 638 | |
| 639 | 3. Disable the use of format=flowed: |
| 640 | Edit..Preferences..Advanced..Config Editor. Search for |
| 641 | "mailnews.send_plaintext_flowed". |
| 642 | Toggle it to make sure it is set to `false`. |
| 643 | |
| 644 | After that is done, you should be able to compose email as you |
| 645 | otherwise would (cut + paste, `git format-patch` | `git imap-send`, etc), |
| 646 | and the patches will not be mangled. |
| 647 | |
| 648 | Approach #3 (external editor) |
| 649 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 650 | |
| 651 | The following Thunderbird extensions are needed: |
| 652 | AboutConfig from https://mjg.github.io/AboutConfig/ and |
| 653 | External Editor from https://globs.org/articles.php?lng=en&pg=8 |
| 654 | |
| 655 | 1. Prepare the patch as a text file using your method of choice. |
| 656 | |
| 657 | 2. Before opening a compose window, use Edit->Account Settings to |
| 658 | uncheck the "Compose messages in HTML format" setting in the |
| 659 | "Composition & Addressing" panel of the account to be used to |
| 660 | send the patch. |
| 661 | |
| 662 | 3. In the main Thunderbird window, _before_ you open the compose |
| 663 | window for the patch, use Tools->about:config to set the |
| 664 | following to the indicated values: |
| 665 | + |
| 666 | ---- |
| 667 | mailnews.send_plaintext_flowed => false |
| 668 | mailnews.wraplength => 0 |
| 669 | ---- |
| 670 | |
| 671 | 4. Open a compose window and click the external editor icon. |
| 672 | |
| 673 | 5. In the external editor window, read in the patch file and exit |
| 674 | the editor normally. |
| 675 | |
| 676 | Side note: it may be possible to do step 2 with |
| 677 | about:config and the following settings but no one's tried yet. |
| 678 | |
| 679 | ---- |
| 680 | mail.html_compose => false |
| 681 | mail.identity.default.compose_html => false |
| 682 | mail.identity.id?.compose_html => false |
| 683 | ---- |
| 684 | |
| 685 | There is a script in contrib/thunderbird-patch-inline which can help |
| 686 | you include patches with Thunderbird in an easy way. To use it, do the |
| 687 | steps above and then use the script as the external editor. |
| 688 | |
| 689 | KMail |
| 690 | ~~~~~ |
| 691 | This should help you to submit patches inline using KMail. |
| 692 | |
| 693 | 1. Prepare the patch as a text file. |
| 694 | |
| 695 | 2. Click on New Mail. |
| 696 | |
| 697 | 3. Go under "Options" in the Composer window and be sure that |
| 698 | "Word wrap" is not set. |
| 699 | |
| 700 | 4. Use Message -> Insert file... and insert the patch. |
| 701 | |
| 702 | 5. Back in the compose window: add whatever other text you wish to the |
| 703 | message, complete the addressing and subject fields, and press send. |
| 704 | |
| 705 | BASE TREE INFORMATION |
| 706 | --------------------- |
| 707 | |
| 708 | The base tree information block is used for maintainers or third party |
| 709 | testers to know the exact state the patch series applies to. It consists |
| 710 | of the "base commit", which is a well-known commit that is part of the |
| 711 | stable part of the project history everybody else works off of, and zero |
| 712 | or more "prerequisite patches", which are well-known patches in flight |
| 713 | that is not yet part of the "base commit" that need to be applied on top |
| 714 | of "base commit" in topological order before the patches can be applied. |
| 715 | |
| 716 | The "base commit" is shown as "`base-commit:` " followed by the 40-hex of |
| 717 | the commit object name. A "prerequisite patch" is shown as |
| 718 | "`prerequisite-patch-id:` " followed by the 40-hex "patch id", which can |
| 719 | be obtained by passing the patch through the `git patch-id --stable` |
| 720 | command. |
| 721 | |
| 722 | Imagine that on top of the public commit P, you applied well-known |
| 723 | patches X, Y and Z from somebody else, and then built your three-patch |
| 724 | series A, B, C, the history would be like: |
| 725 | |
| 726 | ................................................ |
| 727 | ---P---X---Y---Z---A---B---C |
| 728 | ................................................ |
| 729 | |
| 730 | With `git format-patch --base=P -3 C` (or variants thereof, e.g. with |
| 731 | `--cover-letter` or using `Z..C` instead of `-3 C` to specify the |
| 732 | range), the base tree information block is shown at the end of the |
| 733 | first message the command outputs (either the first patch, or the |
| 734 | cover letter), like this: |
| 735 | |
| 736 | ---- |
| 737 | base-commit: P |
| 738 | prerequisite-patch-id: X |
| 739 | prerequisite-patch-id: Y |
| 740 | prerequisite-patch-id: Z |
| 741 | ---- |
| 742 | |
| 743 | For non-linear topology, such as |
| 744 | |
| 745 | ................................................ |
| 746 | ---P---X---A---M---C |
| 747 | \ / |
| 748 | Y---Z---B |
| 749 | ................................................ |
| 750 | |
| 751 | You can also use `git format-patch --base=P -3 C` to generate patches |
| 752 | for A, B and C, and the identifiers for P, X, Y, Z are appended at the |
| 753 | end of the first message. |
| 754 | |
| 755 | If set `--base=auto` in cmdline, it will automatically compute |
| 756 | the base commit as the merge base of tip commit of the remote-tracking |
| 757 | branch and revision-range specified in cmdline. |
| 758 | For a local branch, you need to make it to track a remote branch by `git branch |
| 759 | --set-upstream-to` before using this option. |
| 760 | |
| 761 | EXAMPLES |
| 762 | -------- |
| 763 | |
| 764 | * Extract commits between revisions R1 and R2, and apply them on top of |
| 765 | the current branch using `git am` to cherry-pick them: |
| 766 | + |
| 767 | ------------ |
| 768 | $ git format-patch -k --stdout R1..R2 | git am -3 -k |
| 769 | ------------ |
| 770 | |
| 771 | * Extract all commits which are in the current branch but not in the |
| 772 | origin branch: |
| 773 | + |
| 774 | ------------ |
| 775 | $ git format-patch origin |
| 776 | ------------ |
| 777 | + |
| 778 | For each commit a separate file is created in the current directory. |
| 779 | |
| 780 | * Extract all commits that lead to `origin` since the inception of the |
| 781 | project: |
| 782 | + |
| 783 | ------------ |
| 784 | $ git format-patch --root origin |
| 785 | ------------ |
| 786 | |
| 787 | * The same as the previous one: |
| 788 | + |
| 789 | ------------ |
| 790 | $ git format-patch -M -B origin |
| 791 | ------------ |
| 792 | + |
| 793 | Additionally, it detects and handles renames and complete rewrites |
| 794 | intelligently to produce a renaming patch. A renaming patch reduces |
| 795 | the amount of text output, and generally makes it easier to review. |
| 796 | Note that non-Git `patch` programs won't understand renaming patches, so |
| 797 | use it only when you know the recipient uses Git to apply your patch. |
| 798 | |
| 799 | * Extract three topmost commits from the current branch and format them |
| 800 | as e-mailable patches: |
| 801 | + |
| 802 | ------------ |
| 803 | $ git format-patch -3 |
| 804 | ------------ |
| 805 | |
| 806 | CAVEATS |
| 807 | ------- |
| 808 | |
| 809 | Note that `format-patch` will omit merge commits from the output, even |
| 810 | if they are part of the requested range. A simple "patch" does not |
| 811 | include enough information for the receiving end to reproduce the same |
| 812 | merge commit. |
| 813 | |
| 814 | === PATCH APPLICATION |
| 815 | |
| 816 | include::format-patch-caveats.adoc[] |
| 817 | |
| 818 | SEE ALSO |
| 819 | -------- |
| 820 | linkgit:git-am[1], linkgit:git-send-email[1] |
| 821 | |
| 822 | GIT |
| 823 | --- |
| 824 | Part of the linkgit:git[1] suite |