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

[Carlo Arenas <carenas@gmail.com>]

On Sat, Oct 9, 2021 at 1:57 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 09/10/21 15.31, Carlo Marcelo Arenas Belón wrote:
> > -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)

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