Re: [RFC PATCH] Documentation: better document format-patch options in send-email

On Sat, Oct 9, 2021 at 1:57 AM Bagas Sanjaya [off-list ref] wrote:

On 09/10/21 15.31, Carlo Marcelo Arenas Belón wrote:

quoted

-2. Generic <revision range> expression (see "SPECIFYING
-   REVISIONS" section in linkgit:gitrevisions[7]) means the
-   commits in the specified range.
-
-The first rule takes precedence in the case of a single <commit>.  To
-apply the second rule, i.e., format everything since the beginning of
-history up until <commit>, use the `--root` option: `git format-patch
---root <commit>`.  If you want to format only <commit> itself, you
-can do this with `git format-patch -1 <commit>`.
+2. A Generic <revision range> expression that describes with
+   options and revisions a range of commits.
+
+If you give a single <commit> and nothing else, it is taken as the
+<since> of the first form.  If you want to format everything from the
+beginning of history up until <commit>, use the `--root` option:
+`git format-patch --root <commit>`.  If you want to format only the
+<commit> itself, use instead `git format-patch -1 <commit>`.
+
+If you want to affect a set of commits, provide a range (see
+"SPECIFYING RANGES" section in linkgit:gitrevisions[7]).

Supposed that we have following commit graph:

a --- b --- c --- d --- e --- f (main)
             \
              --- g --- h --- i (mywork, HEAD)

According to your edit, `git format-patch <c>` and `git format-patch
--root <i>` are equivalent, right?

I didn't change the definition of --root with my edit, but I guess it
is still confusing.

the beginning of history from your tree is a, c would be a "fork
point" AFAIK, but if you use --root will get 6 patches (a, b, c, g, h,
i)

quoted

@@ -18,8 +19,8 @@ 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.
+last case, a revision in a format accepted by linkgit:git-format-patch[1]
+as well as relevant options must be provided to git send-email.

  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

Did you mean that in the second form of git send-email, only
format-patch options are accepted?

The synopsis shows "send-email options" are also allowed (as
optional), the mention of "relevant options" here was to indicate
additional options from git-format-patch which make sense (ex: common
diff options, --root, or the options from the range section of
references).

The truth is that you can actually do files, directories and revisions
now, but that is a bug.

Carlo