git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3 2/8] Doc: add more detail for git-format-patch

From
Denton Liu <liu.denton@gmail.com>
Date
May 22, 2019, 02:44 UTC
Message-ID
<a8cc599fd2c6714c92e21d4dee9763c353e5f550.1558492582.git.liu.denton@gmail.com>
In-Reply-To
<cover.1558492582.git.liu.denton@gmail.com>

In git-format-patch.txt, we were missing some key user information. First of all, using the `--to` and `--cc` options don't override `format.to` and `format.cc` variables, respectively. They add on to each other. Document this.

In addition, document the special value of `--base=auto`.
Next, while we're at it, surround option arguments with <>.

Finally, document the `format.outputDirectory` config and change `format.coverletter` to use camelcase.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-format-patch.txt | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 1af85d404f..4e180bbfbb 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -17,9 +17,9 @@ SYNOPSIS
 		   [--signature-file=<file>]
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
-		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
+		   [--in-reply-to=<Message-Id>] [--suffix=.<sfx>]
 		   [--ignore-if-in-upstream]
-		   [--rfc] [--subject-prefix=Subject-Prefix]
+		   [--rfc] [--subject-prefix=<Subject-Prefix>]
 		   [(--reroll-count|-v) <n>]
 		   [--to=<email>] [--cc=<email>]
 		   [--[no-]cover-letter] [--quiet] [--notes[=<ref>]]
@@ -158,7 +158,7 @@ Beware that the default for 'git send-email' is to thread emails
 itself.  If you want `git format-patch` to take care of threading, you
 will want to ensure that threading is disabled for `git send-email`.
 
---in-reply-to=Message-Id::
+--in-reply-to=<Message-Id>::
 	Make the first mail (or all the mails with `--no-thread`) appear as a
 	reply to the given Message-Id, which avoids breaking threads to
 	provide a new patch series.
@@ -192,13 +192,17 @@ will want to ensure that threading is disabled for `git send-email`.
 
 --to=<email>::
 	Add a `To:` header to the email headers. This is in addition
-	to any configured headers, and may be used multiple times.
+	to any configured headers, and may be used multiple times. The
+	emails given will be used along with any emails given by
+	`format.to` configurations.
 	The negated form `--no-to` discards all `To:` headers added so
 	far (from config or command line).
 
 --cc=<email>::
 	Add a `Cc:` header to the email headers. This is in addition
-	to any configured headers, and may be used multiple times.
+	to any configured headers, and may be used multiple times. The
+	emails given will be used along with any emails given by
+	`format.cc` configurations.
 	The negated form `--no-cc` discards all `Cc:` headers added so
 	far (from config or command line).
 
@@ -309,7 +313,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 --base=<commit>::
 	Record the base tree information to identify the state the
 	patch series applies to.  See the BASE TREE INFORMATION section
-	below for details.
+	below for details. If <commit> is equal to "auto", a base commit
+	is automatically chosen.
 
 --root::
 	Treat the revision argument as a <revision range>, even if it
@@ -325,8 +330,9 @@ CONFIGURATION
 -------------
 You can specify extra mail header lines to be added to each message,
 defaults for the subject prefix and file suffix, number patches when
-outputting more than one patch, add "To" or "Cc:" headers, configure
-attachments, and sign off patches with configuration variables.
+outputting more than one patch, add "To:" or "Cc:" headers, configure
+attachments, change the patch output directory, and sign off patches
+with configuration variables.
 
 ------------
 [format]
@@ -338,7 +344,8 @@ attachments, and sign off patches with configuration variables.
 	cc = <email>
 	attach [ = mime-boundary-string ]
 	signOff = true
-	coverletter = auto
+	outputDirectory = <directory>
+	coverLetter = auto
 ------------
 
 

-- 
2.22.0.rc1.169.g49223abbf8
Previous: Denton LiuNext: Denton Liu
Message 38 of 59 in “teach branch-specific options for format-patch”
  1. 0/7 teach branch-specific options for format-patchDenton Liu, May 5, 2019
  2. 1/7 t4014: clean up styleDenton Liu, May 5, 2019
  3. 2/7 Doc: add more detail for git-format-patchDenton Liu, May 5, 2019
  4. 3/7 branch.c: extract read_branch_config functionDenton Liu, May 5, 2019
  5. 4/7 format-patch: make cover letter subject configurableDenton Liu, May 5, 2019
  6. 5/7 format-patch: move extra_headers logic laterDenton Liu, May 5, 2019
  7. 6/7 string-list: create string_list_append_allDenton Liu, May 5, 2019
  8. 7/7 format-patch: read branch-specific To: and Cc: headersDenton Liu, May 5, 2019
  9. Junio C HamanoMay 7, 2019
  10. Denton LiuMay 7, 2019
  11. Junio C HamanoMay 7, 2019
  12. Denton LiuMay 7, 2019
  13. Ævar Arnfjörð BjarmasonMay 7, 2019
  14. Junio C HamanoMay 8, 2019
  15. config: learn the "onbranch:" includeIf conditionDenton Liu, May 31, 2019
  16. Johannes SchindelinMay 31, 2019
  17. Denton LiuMay 31, 2019
  18. Johannes SchindelinMay 31, 2019
  19. Denton LiuMay 31, 2019
  20. config: learn the "onbranch:" includeIf conditionDenton Liu, May 31, 2019
  21. Johannes SchindelinMay 31, 2019
  22. Johannes SchindelinJun 5, 2019
  23. Duy NguyenJun 5, 2019
  24. config: learn the "onbranch:" includeIf conditionDenton Liu, Jun 5, 2019
  25. Johannes SchindelinJun 6, 2019
  26. 0/6 teach branch-specific options for format-patchDenton Liu, May 17, 2019
  27. 1/6 t4014: clean up styleDenton Liu, May 17, 2019
  28. 2/6 Doc: add more detail for git-format-patchDenton Liu, May 17, 2019
  29. 3/6 format-patch: make cover letter subject configurableDenton Liu, May 17, 2019
  30. 4/6 format-patch: move extra_headers logic laterDenton Liu, May 17, 2019
  31. 5/6 string-list: create string_list_append_allDenton Liu, May 17, 2019
  32. 6/6 format-patch: read branch-specific To: and Cc: headersDenton Liu, May 17, 2019
  33. Junio C HamanoMay 17, 2019
  34. Denton LiuMay 17, 2019
  35. Denton LiuMay 17, 2019
  36. 0/8 teach branch-specific options for format-patchDenton Liu, May 22, 2019
  37. 1/8 t4014: clean up styleDenton Liu, May 22, 2019
  38. 2/8 Doc: add more detail for git-format-patchDenton Liu, May 22, 2019
  39. 3/8 format-patch: infer cover letter from branch descriptionDenton Liu, May 22, 2019
  40. 4/8 format-patch: move extra_headers logic laterDenton Liu, May 22, 2019
  41. 5/8 string-list: create string_list_append_allDenton Liu, May 22, 2019
  42. 6/8 format-patch: read branch-specific To: and Cc: headersDenton Liu, May 22, 2019
  43. 7/8 format-patch: move output_directory logic laterDenton Liu, May 22, 2019
  44. 8/8 format-patch: read branch-specific output directoryDenton Liu, May 22, 2019
  45. Denton LiuMay 31, 2019
  46. 0/8 teach branch-specific options for format-patchDenton Liu, Jun 14, 2019
  47. 1/8 t4014: clean up styleDenton Liu, Jun 14, 2019
  48. 2/8 Doc: add more detail for git-format-patchDenton Liu, Jun 14, 2019
  49. 3/8 format-patch: infer cover letter from branch descriptionDenton Liu, Jun 14, 2019
  50. 4/8 format-patch: move extra_headers logic laterDenton Liu, Jun 14, 2019
  51. 6/8 format-patch: read branch-specific To: and Cc: headersDenton Liu, Jun 14, 2019
  52. 5/8 string-list: create string_list_append_allDenton Liu, Jun 14, 2019
  53. 8/8 format-patch: read branch-specific output directoryDenton Liu, Jun 14, 2019
  54. 7/8 format-patch: move output_directory logic laterDenton Liu, Jun 14, 2019
  55. 0/3 format-patch: learn --infer-cover-subject option (also t4014 cleanup)Denton Liu, Oct 15, 2019
  56. 1/3 format-patch: replace erroneous and conditionDenton Liu, Oct 15, 2019
  57. 2/3 format-patch: use enum variablesDenton Liu, Oct 15, 2019
  58. 3/3 format-patch: teach --cover-from-description optionDenton Liu, Oct 15, 2019
  59. Junio C HamanoOct 16, 2019

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.