Re: [PATCH v5 3/3] send-email docs: add format-patch options

From: Bagas Sanjaya <bagasdotme@gmail.com>
Date: Sep 24, 2021, 06:19 UTC
Message-ID: <4c415fd4-a74e-5eb0-061e-39185be623ca@gmail.com>
In-Reply-To: <CAPUEspjxYy4GOABXkzRza-wmKnZAdq-v=OP-9+-wfV2PCnDGwQ@mail.gmail.com>

On 24/09/21 11.53, Carlo Arenas wrote:

Show 6 quoted lines

> no; as Junio explained [1] this omission is intentional while the
> rev-list options that
> got cut to make space are not and are more relevant.
> 
> IMHO leaving [<options>] to imply ALL options (that also include diff
> options, for example) is better

Quoting what you linked:

Show 7 quoted lines

> 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.

I think we need to again modify SYNOPSIS and DESCRIPTIONS to highlight above fact:

---- 8> ----

diff --git a/Documentation/git-send-email.txt 
b/Documentation/git-send-email.txt
index 3db4eab4ba..6002ca1a02 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -9,17 +9,19 @@ 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>] <revision list>...
  'git send-email' --dump-aliases


  DESCRIPTION
  -----------
-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.
+In the first form, take the patches in <file> or <directory> and
+emails them out. In the second form, generate patches from specified
+<revision list> (it can be revision range or explicit list of
+revisions from linkgit:git-rev-list[1]), then emails them out.
+<options> can also include options understood by
+linkgit:git-format-patch[1] if the second form is specified.

  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

-- 
An old man doll... just what I always wanted! - Clara