@matheusbsbs / matheus-bagliano / commits / e9a99ef2da

doc: convert git-format-patch synopsis and options to new style

Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name. Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form. Also update the included files: - diff-options.adoc: backtick-quote the git-format-patch-specific option terms (-p, --no-stat, --max-depth=<depth>) - format-patch-caveats.adoc: convert patch(1) to `patch`(1) Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jean-Noël Avila committed Jul 23, 2026 at 21:19 UTC e9a99ef2dafecf03adc00229a6d5ceb10a8f3058

2 files changed +148 -149

Documentation/diff-options.adoc

+4 -4

@@ -13,8 +13,8 @@ endif::git-diff[]

13 endif::git-format-patch[]

15 ifdef::git-format-patch[]

16 --p::

17 ---no-stat::

16 +`-p`::

17 +`--no-stat`::

18 Generate plain patches without any diffstats.

19 endif::git-format-patch[]

@@ -893,8 +893,8 @@ endif::git-format-patch[]

893 reverted with `--ita-visible-in-index`. Both options are

894 experimental and could be removed in future.

895

896 ---max-depth=<depth>::

897 - For each pathspec given on command line, descend at most `<depth>`

896 +`--max-depth=<depth>`::

897 + For each pathspec given on command line, descend at most _<depth>_

898 levels of directories. A value of `-1` means no limit.

899 Cannot be combined with wildcards in the pathspec.

900 Given a tree containing `foo/bar/baz`, the following list shows the

Documentation/git-format-patch.adoc

+144 -145

@@ -8,8 +8,8 @@ git-format-patch - Prepare patches for e-mail submission

9 SYNOPSIS

10 --------

11 -[verse]

12 -'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]

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]

@@ -40,20 +40,20 @@ DESCRIPTION

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'.

43 +for use with `git am`.

45 A "message" generated by the command consists of three parts:

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

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).

54 * The second and subsequent paragraphs of the commit log message.

56 -* The "patch", which is the "diff -p --stat" output (see

56 +* The "patch", which is the `diff -p --stat` output (see

57 linkgit:git-diff[1]) between the commit and its parent.

59 The log message and the patch are separated by a line with a

@@ -61,18 +61,18 @@ three-dash line.

62 There are two ways to specify which commits to operate on.

64 -1. A single commit, <since>, specifies that the commits leading

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.

66 + that leads to the _<since>_ to be output.

68 -2. Generic <revision-range> expression (see "SPECIFYING

69 - REVISIONS" section in linkgit:gitrevisions[7]) means the

68 +2. Generic _<revision-range>_ expression (see 'SPECIFYING

69 + REVISIONS' section in linkgit:gitrevisions[7]) means the

70 commits in the specified range.

72 -The first rule takes precedence in the case of a single <commit>. To

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

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>`.

78 By default, each output file is numbered sequentially from 1, and uses the

@@ -82,7 +82,7 @@ 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.

85 -If `-o` is specified, output files are created in <dir>. Otherwise

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`.

@@ -108,119 +108,119 @@ OPTIONS

108 :git-format-patch: 1

109 include::diff-options.adoc[]

110

111 --<n>::

112 - Prepare patches from the topmost <n> commits.

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

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::

119 +`-n`::

120 +`--numbered`::

121 Name output in '[PATCH n/m]' format, even with a single patch.

122

123 --N::

124 ---no-numbered::

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.

127 +`--start-number <n>`::

128 + Start numbering the patches at _<n>_ instead of 1.

129

130 ---numbered-files::

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::

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::

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::

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>]::

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::

154 +`--no-attach`::

155 Disable the creation of an attachment, overriding the

156 configuration setting.

157

158 ---inline[=<boundary>]::

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 - Controls addition of `In-Reply-To` and `References` headers to

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

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'

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

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>::

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

185 + reply to the given _<message-id>_, which avoids breaking threads to

186 provide a new patch series.

187

188 ---ignore-if-in-upstream::

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

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::

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 - Controls which parts of the cover letter will be automatically

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 -If `<mode>` is `message` or `default`, the cover letter subject will be

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.

207 -+

208 -If `<mode>` is `subject`, the first paragraph of the branch description will

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.

211 -+

212 -If `<mode>` is `auto`, if the first paragraph of the branch description

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.

215 -+

216 -If `<mode>` is `none`, both the cover letter subject and body will be

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

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>::

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.

@@ -231,14 +231,14 @@ 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>::

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

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>]::

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.

@@ -254,38 +254,38 @@ 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

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.

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

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>::

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>::

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

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

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 +

@@ -296,8 +296,8 @@ 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::

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

@@ -308,7 +308,7 @@ feeding the result to `git send-email`.

308 Defaults to the value of the `format.forceInBodyFrom`

309 configuration variable.

310

311 ---add-header=<header>::

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"`.

@@ -316,13 +316,13 @@ feeding the result to `git send-email`.

316 `Cc:`, and custom) headers added so far from config or command

317 line.

318

319 ---cover-letter::

320 ---no-cover-letter::

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>::

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)`.

@@ -334,28 +334,28 @@ feeding the result to `git send-email`.

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::

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>::

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

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>::

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

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

@@ -367,7 +367,7 @@ 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>::

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])

@@ -378,8 +378,8 @@ 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::

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 +

@@ -394,17 +394,17 @@ configuration options in linkgit:git-notes[1] to use this workflow).

394 The default is `--no-notes`, unless the `format.notes` configuration is

395 set.

396

397 ---signature=<signature>::

398 ---no-signature::

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

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.

404 +`--signature-file=<file>`::

405 + Works just like `--signature` except the signature is read from a file.

406

407 ---suffix=.<sfx>::

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`

@@ -413,36 +413,36 @@ set.

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::

416 +`-q`::

417 +`--quiet`::

418 Do not print the names of the generated files to standard output.

419

420 ---no-binary::

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::

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>]::

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

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

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

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::

445 +`--progress`::

446 Show progress reports on stderr as patches are generated.

447

448 CONFIGURATION

@@ -453,7 +453,7 @@ 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 -------------

456 +----

457 [format]

458 headers = "Organization: git-foo\n"

459 subjectPrefix = CHANGE

@@ -467,17 +467,16 @@ with configuration variables.

467 coverLetter = auto

468 commitListFormat = shortlog

469 coverFromDescription = auto

470 -------------

471 -

470 +----

471

472 DISCUSSION

473 ----------

474

476 -The patch produced by 'git format-patch' is in UNIX mailbox format,

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

480 -------------

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

@@ -492,7 +491,7 @@ arch/arm config files were slimmed down using a python script

491

492 Do the same for ia64 so we can have sleek & trim looking

493 ...

495 -------------

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

@@ -502,12 +501,12 @@ 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

505 -'git format-patch' can be tweaked to take advantage of the 'git am

506 ---scissors' feature. After your response to the discussion comes a

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

510 -------------

509 +----

510 ...

511 > So we should do such-and-such.

512

@@ -518,7 +517,7 @@ 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 ...

521 -------------

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

@@ -540,7 +539,7 @@ two common types of corruption:

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

543 - with To: and Cc: lines that do not contain the list and

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,

@@ -561,12 +560,12 @@ If it does not apply correctly, there can be various reasons.

560 this case.

561

562 * The MUA corrupted your patch; "am" would complain that

564 - the patch does not apply. Look in the .git/rebase-apply/ subdirectory and

565 - see what 'patch' file contains and check for the common

566 - corruption patterns mentioned above.

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

568 -* While at it, check the 'info' and 'final-commit' files as well.

569 - If what is in 'final-commit' is not exactly what you would want to

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

@@ -582,11 +581,11 @@ 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

585 -use "git send-email" and send your patches through the GMail SMTP server, or

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

589 -For hints on using 'git send-email' to send your patches through the

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

@@ -595,7 +594,7 @@ section of linkgit:git-imap-send[1].

594 Thunderbird

595 ~~~~~~~~~~~

596 By default, Thunderbird will both wrap emails as well as flag

598 -them as being 'format=flowed', both of which will make the

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,

@@ -609,14 +608,14 @@ 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

612 -(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to

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

619 -(about:config). These are listed on the download page.

618 +(`about:config`). These are listed on the download page.

619

620 Approach #2 (configuration)

621 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

@@ -643,7 +642,7 @@ Toggle it to make sure it is set to `false`. Also, search for

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

646 -otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),

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)

@@ -660,14 +659,14 @@ External Editor from https://globs.org/articles.php?lng=en&pg=8

659 "Composition & Addressing" panel of the account to be used to

660 send the patch.

661

663 -3. In the main Thunderbird window, 'before' you open the compose

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 +

667 -----------

666 +----

667 mailnews.send_plaintext_flowed => false

668 mailnews.wraplength => 0

670 -----------

669 +----

670

671 4. Open a compose window and click the external editor icon.

672

@@ -677,11 +676,11 @@ External Editor from https://globs.org/articles.php?lng=en&pg=8

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

680 -----------

679 +----

680 mail.html_compose => false

681 mail.identity.default.compose_html => false

682 mail.identity.id?.compose_html => false

684 -----------

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

@@ -708,15 +707,15 @@ BASE TREE INFORMATION

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

711 -of the 'base commit', which is a well-known commit that is part of the

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

713 -or more 'prerequisite patches', which are well-known patches in flight

714 -that is not yet part of the 'base commit' that need to be applied on top

715 -of 'base commit' in topological order before the patches can be applied.

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

717 -The 'base commit' is shown as "base-commit: " followed by the 40-hex of

718 -the commit object name. A 'prerequisite patch' is shown as

719 -"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can

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

@@ -734,12 +733,12 @@ 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

737 -------------

736 +----

737 base-commit: P

738 prerequisite-patch-id: X

739 prerequisite-patch-id: Y

740 prerequisite-patch-id: Z

742 -------------

741 +----

742

743 For non-linear topology, such as

744

@@ -763,7 +762,7 @@ EXAMPLES

762 --------

763

764 * Extract commits between revisions R1 and R2, and apply them on top of

766 - the current branch using 'git am' to cherry-pick them:

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

@@ -778,7 +777,7 @@ $ git format-patch origin

777 +

778 For each commit a separate file is created in the current directory.

779

781 -* Extract all commits that lead to 'origin' since the inception of the

780 +* Extract all commits that lead to `origin` since the inception of the

781 project:

782 +

783 ------------

@@ -794,7 +793,7 @@ $ git format-patch -M -B origin

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.

797 -Note that non-Git "patch" programs won't understand renaming patches, so

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