Re: [PATCH RESEND] format-patch: add --description-file option

[Junio C Hamano <gitster@pobox.com>]

Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes:

> When formatting patches from a detached HEAD, there is no branch
> description to derive the cover letter from. While with format-patch
> one could post-process the generated file (which would be ugly enough),
> scripting that with send-email would be *really* ugly. So add an option
> to feed a description directly.

I think it makes sense to give the same set of features to those who
run format-patch from a detached HEAD as to those who run it on a
branch.  But personally I am not interested in a new feature that
encourages use of send-email as a front-end to format-patch, which I
consider is a misfeature, to make it easier for a set of patches
without final proofreading to be sent out.

Having said that, with my maintainer hat on, if we were to add a new
feature to format-patch, it makes sense to allow it passed through
send-email as well, since the (mis)feature already exists.

Please elaborate a bit more on the use case, though.

 * "there is no branch description to derive from" makes a reader
   wonder what the workflow would become if you could do "git branch
   --add-description HEAD" to prepare a description, which would
   imply that what is more desirable might be a feature enhancement
   of the "branch" command, not "format-patch" or "send-email", to
   allow you to describe what you are doing on the HEAD.

 * Or does the end-user have a branch with description already
   prepared, but for some untold reason the tip of the branch is
   checked out on a detached HEAD?

   If so, an obviously better alternative design would be to add a
   feature that passes a branch name to format-patch and tell it to
   pretend that the user is working on the branch.  That way, not
   just "description", any feature that makes the command use "which
   branch are we on?" information to enhance its behaviour we have
   right now or we will add to the command will all benefit.  For
   example, builtin/log.c::cmd_format_match() uses branch_name only
   for calling read_branch_desc() via prepare_cover_text(), but it
   is perfectly reasonable for us to make the range-diff default
   derived based on the reflog of the "current branch" on, and
   "pretend we were on this branch" may help you in such a case.

In other words, if a particular solution proposed (or not proposed)
is sensible or not heavily depends on how the end-user ends up
running format-patch (and sending the output out) on a detached
HEAD, and where does the end-user want to take the description
information from. No, the answer to the latter is not "the file
specified with the --description-file option"; that is not a valid
answer.  The question is about how the contents of that file is
populated and maintained.

A feature to specify the template used when generating the cover
letter may also work well for such a use case.  Among placeholders
to specify where to place auto-generated things like:

 - shortlog information
 - other ways to list commits in the series (e.g. listing of commit
   titles from "git log --oneline -r" may be more appropriate and
   readable than "shortlog" output especially when the series was
   written by multiple authors),
 - diffstat

there would be a placeholder to stuff branch description output (for
the normal case), and in your detached HEAD use case, you'd prepare
such a template without using branch description placeholder, but
instead prepare the description in place in the template before
running format-patch.  Which might actually be a better alternative.

But all of that depends on what the expected use case to support is.

Thanks.