"Aleen via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
> From: Aleen <aleen42@xxxxxxxxxx>
> Subject: Re: [PATCH v2 1/4] doc: git-format-patch: specify the option --always
"specify" -> "describe", perhaps?
> Signed-off-by: Aleen <aleen42@xxxxxxxxxx>
> ---
> Documentation/git-format-patch.txt | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 113eabc107c..a9f2bf94182 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -30,6 +30,7 @@ SYNOPSIS
> [--range-diff=<previous> [--creation-factor=<percent>]]
> [--filename-max-length=<n>]
> [--progress]
> + [--always]
> [<common diff options>]
> [ <since> | <revision range> ]
>
> @@ -388,6 +389,10 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
> --progress::
> Show progress reports on stderr as patches are generated.
>
> +--always::
> + Patch commits with detailed commit messages,
> + even if they emit no changes. (see linkgit:git-diff-tree[1])
What does the verb "Patch" mean here? It cannot be what the command
"patch" does, i.e. apply a diff to working tree files, as
format-patch does not apply any patch.
Who guarantees that commit messages are detailed? If I write a
commit that does not change anything with a one-liner message, would
this option make that message more detailed? I doubt that it would
be the case.
This option may sit much better near the --ignore-if-in-upstream
option. The primary way the command is told which commits to show
is via its argument (<since> or <revision-range>), and we do not
have many options to affect the selection of commits, but this one
and --ignore-if-in-upstream are such options. Borrowing from the
way the description of that other option is phrased, perhaps
Include patches for commits that do not introduce any change,
which are omitted by default.
Do not refer to 'git-diff-tree'; I do not think the reader who is
learning how to drive format-patch will learn anything new by
reading that page.
I have a feeling that if we were to endorse and promote this option
by documenting (note: it was an accident and a mistake that this
option is understood by underlying revision.c parse machinery, and
not a designed behaviour for format-patch to do anything to empty
commits), we should give users a better synonym to invoke it, but
that can and should be outside of this step.
