Re: [PATCH 2/3] Doc: add more detail for git-format-patch

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Aug 19, 2019, 17:09 UTC
Message-ID: <CAPig+cSG6mHCgLRw=QLWkVhK4oVSFkQRCszrBdO6SCGA+M0B3Q@mail.gmail.com>
In-Reply-To: <7619da962d1fc804392e3552fbd56bf4bc68ac38.1566182184.git.liu.denton@gmail.com>

On Sun, Aug 18, 2019 at 10:37 PM Denton Liu <liu.denton@gmail.com> wrote:

Show 11 quoted lines

> In git-format-patch.txt, we were missing some key user information.
> First of all, using the `--to` and `--cc` options don't override
> `format.to` and `format.cc` variables, respectively. They add on to each
> other. Document this.
>
> In addition, document the special value of `--base=auto`.
>
> Next, while we're at it, surround option arguments with <>.
>
> Finally, document the `format.outputDirectory` config and change
> `format.coverletter` to use camelcase.

I can't figure out if you typeset "camelcase" like that intentionally, as opposed to "camelCase" or "camel case" or "camel-case".

Show 9 quoted lines

> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
>  --to=<email>::
>         Add a `To:` header to the email headers. This is in addition
> -       to any configured headers, and may be used multiple times.
> +       to any configured headers, and may be used multiple times. The
> +       emails given will be used along with any emails given by
> +       `format.to` configurations.

Hmph. This seems redundant. The description already says "This is in addition to...", so a new sentence saying "...used along with..." is just parroting what was already stated.

Show 9 quoted lines

>         The negated form `--no-to` discards all `To:` headers added so
>         far (from config or command line).
> @@ -314,7 +318,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
>  --base=<commit>::
>         Record the base tree information to identify the state the
>         patch series applies to.  See the BASE TREE INFORMATION section
> -       below for details.
> +       below for details. If <commit> is equal to "auto", a base commit
> +       is automatically chosen.

"is equal to" is unnecessarily technical-sounding. How about:

    If <commit> is "auto", ...