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

[PATCH v3 3/8] format-patch: infer cover letter from branch description

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

We used to populate the subject of the cover letter generated by git-format-patch with "*** SUBJECT HERE ***". However, if a user submits multiple patchsets, they may want to keep a consistent subject between rerolls.

If git-format-patch is run with `--infer-cover-letter` or `format.inferCoverSubject`, infer the subject for the cover letter from the top line(s) of a branch description, similar to how a subject is read from a commit message.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/config/format.txt    |  5 +++
 Documentation/git-format-patch.txt | 10 ++++++
 builtin/log.c                      | 58 ++++++++++++++++++------------
 t/t4014-format-patch.sh            | 33 +++++++++++++++++
 4 files changed, 84 insertions(+), 22 deletions(-)
diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt
index dc77941c48..c8b28fe47f 100644
--- a/Documentation/config/format.txt
+++ b/Documentation/config/format.txt
@@ -36,6 +36,11 @@ format.subjectPrefix::
 	The default for format-patch is to output files with the '[PATCH]'
 	subject prefix. Use this variable to change that prefix.
 
+format.<branch-name>.inferCoverSubject::
+	A boolean that controls whether or not to infer the subject for
+	the cover letter based on the branch's description. See the
+	--infer-cover-subject option in linkgit:git-format-patch[1].
+
 format.signature::
 	The default for format-patch is to output a signature containing
 	the Git version number. Use this variable to change that default.
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 4e180bbfbb..f54aecf4bf 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -19,6 +19,7 @@ SYNOPSIS
 		   [--start-number <n>] [--numbered-files]
 		   [--in-reply-to=<Message-Id>] [--suffix=.<sfx>]
 		   [--ignore-if-in-upstream]
+		   [--[no-]infer-cover-subject]
 		   [--rfc] [--subject-prefix=<Subject-Prefix>]
 		   [(--reroll-count|-v) <n>]
 		   [--to=<email>] [--cc=<email>]
@@ -170,6 +171,14 @@ will want to ensure that threading is disabled for `git send-email`.
 	patches being generated, and any patch that matches is
 	ignored.
 
+--[no-]infer-cover-subject::
+	Instead of using the default "*** SUBJECT HERE ***" subject for
+	the cover letter, infer the subject from the branch's
+	description.
++
+Similar to a commit message, the subject is inferred as the beginning of
+the description up to and excluding the first blank line.
+
 --subject-prefix=<Subject-Prefix>::
 	Instead of the standard '[PATCH]' prefix in the subject
 	line, instead use '[<Subject-Prefix>]'. This
@@ -346,6 +355,7 @@ with configuration variables.
 	signOff = true
 	outputDirectory = <directory>
 	coverLetter = auto
+	inferCoverSubject = true
 ------------
 
 
diff --git a/builtin/log.c b/builtin/log.c
index e43ee12fb1..617f074d60 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -769,6 +769,7 @@ static const char *signature = git_version_string;
 static const char *signature_file;
 static int config_cover_letter;
 static const char *config_output_directory;
+static int infer_cover_subject;
 
 enum {
 	COVER_UNSET,
@@ -864,6 +865,10 @@ static int git_format_config(const char *var, const char *value, void *cb)
 			from = NULL;
 		return 0;
 	}
+	if (!strcmp(var, "format.infercoversubject")) {
+		infer_cover_subject = git_config_bool(var, value);
+		return 0;
+	}
 
 	return git_log_config(var, value, cb);
 }
@@ -970,20 +975,6 @@ static void print_signature(FILE *file)
 	putc('\n', file);
 }
 
-static void add_branch_description(struct strbuf *buf, const char *branch_name)
-{
-	struct strbuf desc = STRBUF_INIT;
-	if (!branch_name || !*branch_name)
-		return;
-	read_branch_desc(&desc, branch_name);
-	if (desc.len) {
-		strbuf_addch(buf, '\n');
-		strbuf_addbuf(buf, &desc);
-		strbuf_addch(buf, '\n');
-	}
-	strbuf_release(&desc);
-}
-
 static char *find_branch_name(struct rev_info *rev)
 {
 	int i, positive = -1;
@@ -1034,13 +1025,17 @@ static void make_cover_letter(struct rev_info *rev, int use_stdout,
 			      struct commit *origin,
 			      int nr, struct commit **list,
 			      const char *branch_name,
+			      int infer_subject,
 			      int quiet)
 {
 	const char *committer;
-	const char *body = "*** SUBJECT HERE ***\n\n*** BLURB HERE ***\n";
-	const char *msg;
+	const char *subject = "*** SUBJECT HERE ***";
+	const char *body = "*** BLURB HERE ***";
+	const char *description = NULL;
 	struct shortlog log;
 	struct strbuf sb = STRBUF_INIT;
+	struct strbuf description_sb = STRBUF_INIT;
+	struct strbuf subject_sb = STRBUF_INIT;
 	int i;
 	const char *encoding = "UTF-8";
 	int need_8bit_cte = 0;
@@ -1068,17 +1063,34 @@ static void make_cover_letter(struct rev_info *rev, int use_stdout,
 	if (!branch_name)
 		branch_name = find_branch_name(rev);
 
-	msg = body;
+	if (branch_name && *branch_name)
+		read_branch_desc(&description_sb, branch_name);
+
+	if (description_sb.len) {
+		if (infer_subject) {
+			description = format_subject(&subject_sb, description_sb.buf, " ");
+			subject = subject_sb.buf;
+		} else {
+			description = description_sb.buf;
+		}
+	}
+
 	pp.fmt = CMIT_FMT_EMAIL;
 	pp.date_mode.type = DATE_RFC2822;
 	pp.rev = rev;
 	pp.print_email_subject = 1;
 	pp_user_info(&pp, NULL, &sb, committer, encoding);
-	pp_title_line(&pp, &msg, &sb, encoding, need_8bit_cte);
-	pp_remainder(&pp, &msg, &sb, 0);
-	add_branch_description(&sb, branch_name);
+	pp_title_line(&pp, &subject, &sb, encoding, need_8bit_cte);
+	pp_remainder(&pp, &body, &sb, 0);
+	if (description) {
+		strbuf_addch(&sb, '\n');
+		strbuf_addstr(&sb, description);
+		strbuf_addch(&sb, '\n');
+	}
 	fprintf(rev->diffopt.file, "%s\n", sb.buf);
 
+	strbuf_release(&description_sb);
+	strbuf_release(&subject_sb);
 	strbuf_release(&sb);
 
 	shortlog_init(&log);
@@ -1554,6 +1566,8 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
 		{ OPTION_CALLBACK, 0, "rfc", &rev, NULL,
 			    N_("Use [RFC PATCH] instead of [PATCH]"),
 			    PARSE_OPT_NOARG | PARSE_OPT_NONEG, rfc_callback },
+		OPT_BOOL(0, "infer-cover-subject", &infer_cover_subject,
+			    N_("infer a cover letter subject from the branch description")),
 		{ OPTION_CALLBACK, 0, "subject-prefix", &rev, N_("prefix"),
 			    N_("Use [<prefix>] instead of [PATCH]"),
 			    PARSE_OPT_NONEG, subject_prefix_callback },
@@ -1617,8 +1631,8 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
 	extra_to.strdup_strings = 1;
 	extra_cc.strdup_strings = 1;
 	init_log_defaults();
-	git_config(git_format_config, NULL);
 	repo_init_revisions(the_repository, &rev, prefix);
+	git_config(git_format_config, NULL);
 	rev.commit_format = CMIT_FMT_EMAIL;
 	rev.expand_tabs_in_log_default = 0;
 	rev.verbose_header = 1;
@@ -1893,7 +1907,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
 		if (thread)
 			gen_message_id(&rev, "cover");
 		make_cover_letter(&rev, use_stdout,
-				  origin, nr, list, branch_name, quiet);
+				  origin, nr, list, branch_name, infer_cover_subject, quiet);
 		print_bases(&bases, rev.diffopt.file);
 		print_signature(rev.diffopt.file);
 		total++;
diff --git a/t/t4014-format-patch.sh b/t/t4014-format-patch.sh
index 3423f974bc..4cb6b9edfa 100755
--- a/t/t4014-format-patch.sh
+++ b/t/t4014-format-patch.sh
@@ -1469,6 +1469,39 @@ test_expect_success 'format patch ignores color.ui' '
 	test_cmp expect actual
 '
 
+test_expect_success 'cover letter with config subject' '
+	test_config branch.rebuild-1.description "config subject
+
+body" &&
+	test_config format.inferCoverSubject true &&
+	git checkout rebuild-1 &&
+	git format-patch --stdout --cover-letter master >actual &&
+	grep "^Subject: \[PATCH 0/2\] config subject$" actual &&
+	grep "^body" actual
+'
+
+test_expect_success 'cover letter with command-line subject' '
+	test_config branch.rebuild-1.description "command-line subject
+
+body" &&
+	git checkout rebuild-1 &&
+	git format-patch --stdout --cover-letter --infer-cover-subject master >actual &&
+	grep "^Subject: \[PATCH 0/2\] command-line subject$" actual &&
+	grep "^body" actual
+'
+
+test_expect_success 'cover letter with command-line --no-infer-cover-subject overrides config' '
+	test_config branch.rebuild-1.description "config subject
+
+body" &&
+	test_config format.inferCoverSubject true &&
+	git checkout rebuild-1 &&
+	git format-patch --stdout --cover-letter --no-infer-cover-subject master >actual &&
+	grep "^Subject: \[PATCH 0/2\] \*\*\* SUBJECT HERE \*\*\*$" actual &&
+	grep "^config subject" actual &&
+	grep "^body" actual
+'
+
 test_expect_success 'cover letter using branch description (1)' '
 	git checkout rebuild-1 &&
 	test_config branch.rebuild-1.description hello &&

-- 
2.22.0.rc1.169.g49223abbf8
Previous: Denton LiuNext: Denton Liu
Message 39 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.