format-patch: add ability to use alt cover format

Often when sending patch series there's a need to clarify to the
reviewer what's the purpose of said series, since it might be difficult
to understand it from reading the commits messages one by one.

"git format-patch" provides the useful "--cover-letter" flag to declare
if we want it to generate a template for us to use. By default it will
generate a "git shortlog" of the changes, which developers find less
useful than they'd like, mainly because the shortlog groups commits by
author, and gives no obvious chronological order.

Give format-patch the ability to specify an alternative format spec
through the "--cover-letter-format" option. This option either takes
"shortlog", which is the current format, or a format spec prefixed with
"log:".

Example:
    git format-patch --cover-letter \
        --cover-letter-format="log:[%(count)/%(total)] %s (%an)" HEAD~3

    [1/3] this is a commit summary (Mirko Faina)
    [2/3] this is another commit summary (Mirko Faina)
    ...

Signed-off-by: Mirko Faina <mroik@delayed.space>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/builtin/log.c b/builtin/log.c
index 0d12272031f0038b17fe8cdfa405fb6f77b80653..95e5d9755fac6d42864c72a6553b1713828dc685 100644 (file)
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1343,13 +1343,36 @@ static void generate_shortlog_cover_letter(struct shortlog *log,
        shortlog_output(log);
 }
 
+static void generate_commit_list_cover(FILE *cover_file, const char *format,
+                                      struct commit **list, int n)
+{
+       struct strbuf commit_line = STRBUF_INIT;
+       struct pretty_print_context ctx = {0};
+       struct rev_info rev = REV_INFO_INIT;
+
+       strbuf_init(&commit_line, 0);
+       rev.total = n;
+       ctx.rev = &rev;
+       for (int i = n - 1; i >= 0; i--) {
+               rev.nr = n - i;
+               repo_format_commit_message(the_repository, list[i], format,
+                               &commit_line, &ctx);
+               fprintf(cover_file, "%s\n", commit_line.buf);
+               strbuf_reset(&commit_line);
+       }
+       fprintf(cover_file, "\n");
+
+       strbuf_release(&commit_line);
+}
+
 static void make_cover_letter(struct rev_info *rev, int use_separate_file,
                              struct commit *origin,
                              int nr, struct commit **list,
                              const char *description_file,
                              const char *branch_name,
                              int quiet,
-                             const struct format_config *cfg)
+                             const struct format_config *cfg,
+                             const char *format)
 {
        const char *committer;
        struct shortlog log;
@@ -1396,7 +1419,12 @@ static void make_cover_letter(struct rev_info *rev, int use_separate_file,
        free(pp.after_subject);
        strbuf_release(&sb);
 
-       generate_shortlog_cover_letter(&log, rev, list, nr);
+       if (skip_prefix(format, "log:", &format))
+               generate_commit_list_cover(rev->diffopt.file, format, list, nr);
+       else if (!strcmp(format, "shortlog"))
+               generate_shortlog_cover_letter(&log, rev, list, nr);
+       else
+               die(_("'%s' is not a valid format string"), format);
 
        /* We can only do diffstat with a unique reference point */
        if (origin)
@@ -1914,6 +1942,7 @@ int cmd_format_patch(int argc,
        int just_numbers = 0;
        int ignore_if_in_upstream = 0;
        int cover_letter = -1;
+       const char *cover_letter_fmt = NULL;
        int boundary_count = 0;
        int no_binary_diff = 0;
        int zero_commit = 0;
@@ -1960,6 +1989,8 @@ int cmd_format_patch(int argc,
                            N_("print patches to standard out")),
                OPT_BOOL(0, "cover-letter", &cover_letter,
                            N_("generate a cover letter")),
+               OPT_STRING(0, "cover-letter-format", &cover_letter_fmt, N_("format-spec"),
+                           N_("format spec used for the commit list in the cover letter")),
                OPT_BOOL(0, "numbered-files", &just_numbers,
                            N_("use simple number sequence for output file names")),
                OPT_STRING(0, "suffix", &fmt_patch_suffix, N_("sfx"),
@@ -2297,6 +2328,7 @@ int cmd_format_patch(int argc,
                /* nothing to do */
                goto done;
        total = list.nr;
+
        if (cover_letter == -1) {
                if (cfg.config_cover_letter == COVER_AUTO)
                        cover_letter = (total > 1);
@@ -2383,12 +2415,14 @@ int cmd_format_patch(int argc,
        }
        rev.numbered_files = just_numbers;
        rev.patch_suffix = fmt_patch_suffix;
+
        if (cover_letter) {
                if (cfg.thread)
                        gen_message_id(&rev, "cover");
                make_cover_letter(&rev, !!output_directory,
                                  origin, list.nr, list.items,
-                                 description_file, branch_name, quiet, &cfg);
+                                 description_file, branch_name, quiet, &cfg,
+                                 cover_letter_fmt);
                print_bases(&bases, rev.diffopt.file);
                print_signature(signature, rev.diffopt.file);
                total++;

diff --git a/t/t4014-format-patch.sh b/t/t4014-format-patch.sh
index 21d6d0cd9ef679c04534fb9fa61952546c63c740..458da80721a1e97d5ff80a64e29c5588cf4d4ab7 100755 (executable)
--- a/t/t4014-format-patch.sh
+++ b/t/t4014-format-patch.sh
@@ -380,6 +380,54 @@ test_expect_success 'filename limit applies only to basename' '
        done
 '
 
+test_expect_success 'cover letter with subject, author and count' '
+       rm -rf patches &&
+       test_when_finished "git reset --hard HEAD~1" &&
+       test_when_finished "rm -rf patches result test_file" &&
+       touch test_file &&
+       git add test_file &&
+       git commit -m "This is a subject" &&
+       git format-patch --cover-letter \
+       --cover-letter-format="log:[%(count)/%(total)] %s (%an)" -o patches HEAD~1 &&
+       grep "^\[1/1\] This is a subject (A U Thor)$" patches/0000-cover-letter.patch >result &&
+       test_line_count = 1 result
+'
+
+test_expected_success 'cover letter with author and count' '
+       test_when_finished "git reset --hard HEAD~1" &&
+       test_when_finished "rm -rf patches result test_file" &&
+       touch test_file &&
+       git add test_file &&
+       git commit -m "This is a subject" &&
+       git format-patch --cover-letter \
+       --cover-letter-format="log:[%(count)/%(total)] %an" -o patches HEAD~1 &&
+       grep "^\[1/1\] A U Thor$" patches/0000-cover-letter.patch >result &&
+       test_line_count = 1 result
+'
+
+test_expect_success 'cover letter shortlog' '
+       test_when_finished "git reset --hard HEAD~1" &&
+       test_when_finished "rm -rf patches result test_file" &&
+       touch test_file &&
+       git add test_file &&
+       git commit -m "This is a subject" &&
+       git format-patch --cover-letter --cover-letter-format=shortlog \
+       -o patches HEAD~1 &&
+       sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result &&
+       test_line_count = 1 result
+'
+
+test_expect_success 'cover letter no format' '
+       test_when_finished "git reset --hard HEAD~1" &&
+       test_when_finished "rm -rf patches result test_file" &&
+       touch test_file &&
+       git add test_file &&
+       git commit -m "This is a subject" &&
+       git format-patch --cover-letter -o patches HEAD~1 &&
+       sed -n -e "/^A U Thor/p;" patches/0000-cover-letter.patch >result &&
+       test_line_count = 1 result
+'
+
 test_expect_success 'reroll count' '
        rm -fr patches &&
        git format-patch -o patches --cover-letter --reroll-count 4 main..side >list &&

diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
index 964e1f156932c6c13b506185f508b877b2a2ca00..4f760a746862c32f97550c6f645d5058d6ecce41 100755 (executable)
--- a/t/t9902-completion.sh
+++ b/t/t9902-completion.sh
@@ -2774,6 +2774,7 @@ test_expect_success PERL 'send-email' '
        test_completion "git send-email --cov" <<-\EOF &&
        --cover-from-description=Z
        --cover-letter Z
+       --cover-letter-format=Z
        EOF
        test_completion "git send-email --val" <<-\EOF &&
        --validate Z