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

[Bagas Sanjaya <bagasdotme@gmail.com>]

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 since 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 think for the third case, s/affect/format/.

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

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