Re: [PATCH v2 3/3] send-email docs: mention format-patch options

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 20, 2021, 20:32 UTC
Message-ID: <xmqqh7fjuaar.fsf@gitster.g>
In-Reply-To: <20210820004604.9948-4-tbperrotta@gmail.com>

Thiago Perrotta <tbperrotta@gmail.com> writes:

> Currently git-send-email(1) does not make it explicit that format-patch
> options are accepted.

It may be a feature ;-), as running format-patch while send-email is running encourages a wrong workflow.

But as long as we allow users to do so, we'd need to desribe it.

Show 15 quoted lines

> Signed-off-by: Thiago Perrotta <tbperrotta@gmail.com>
> ---
>  Documentation/git-send-email.txt | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
> index 3db4eab4ba..05dd8ded44 100644
> --- a/Documentation/git-send-email.txt
> +++ b/Documentation/git-send-email.txt
> @@ -42,6 +42,8 @@ and the "Subject:" of the message as the second line.
>  OPTIONS
>  -------
>  
> +Options from linkgit:git-format-patch[1] are also accepted.
> +

The program works in two majorly different modes.  It either takes

 * message files that are already proof-read and copy-edited from
   the filesystem and sends them out, or

 * format-patch options to generate message files out of the commits
   and send them out without any proofreading.

The documentation for OPTIONS has various sections, starting from Composing, then Sending, Automating, Administering, and Information.

By having this new sentence before all the sections gives a wrong impression that format-patch options are accepted in both modes. But the format-patch options are relevant only when we are using the latter operation mode. Unlike that, all the options documented under these sections starting from Composing are applicable to both modes.

We may want to clarify that we have two modes near the top of the document, perhaps like the attached, and extend the description a bit there.

 Documentation/git-send-email.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git c/Documentation/git-send-email.txt w/Documentation/git-send-email.txt
index 3db4eab4ba..8adc8ace79 100644
--- c/Documentation/git-send-email.txt
+++ w/Documentation/git-send-email.txt
@@ -9,7 +9,8 @@ git-send-email - Send a collection of patches as emails
 SYNOPSIS
 --------
 [verse]
-'git send-email' [<options>] <file|directory|rev-list options>...
+'git send-email' [<options>] <file|directory>...
+'git send-email' [<options>] <format-patch options>
 'git send-email' --dump-aliases
 
 
@@ -19,7 +20,8 @@ Takes the patches given on the command line and emails them out.
 Patches can be specified as files, directories (which will send all
 files in the directory), or directly as a revision list.  In the
 last case, any format accepted by linkgit:git-format-patch[1] can
-be passed to git send-email.
+be passed to git send-email, and options understood by
+linkgit:git-format-patch[1] can be passed.
 
 The header of the email is configurable via command-line options.  If not
 specified on the command line, the user will be prompted with a ReadLine