On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget <gitgitgadget@xxxxxxxxx> wrote: > > From: Linus Arver <linusa@xxxxxxxxxx> > > The command can take inputs that are either just a commit message, or > an email-like output such as git-format-patch which includes a commit > message, "---" divider, and patch part. The existing explanation blends > these two inputs together in the first sentence > > This command reads some patches or commit messages > > which then necessitates using the "commit message part" phrasing (as > opposed to just "commit message") because the input is ambiguous per the > above definition. > > This change separates the two input types and explains them separately, > and so there is no longer a need to use the "commit message part" > phrase. > > Signed-off-by: Linus Arver <linusa@xxxxxxxxxx> > --- > Documentation/git-interpret-trailers.txt | 35 +++++++++++++----------- > 1 file changed, 19 insertions(+), 16 deletions(-) > > diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt > index da8fec7d5fe..ffde97a6c3d 100644 > --- a/Documentation/git-interpret-trailers.txt > +++ b/Documentation/git-interpret-trailers.txt > @@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail > headers, at the end of the otherwise free-form part of a commit > message. > > -This command reads some patches or commit messages from either the > -<file> arguments or the standard input if no <file> is specified. If > -`--parse` is specified, the output consists of the parsed trailers. > - > +This command reads commit messages from either the > +<file> arguments or the standard input if no <file> is specified. > +If `--parse` is specified, the output consists of the parsed trailers. > Otherwise, this command applies the arguments passed using the > -`--trailer` option, if any, to the commit message part of each input > -file. The result is emitted on the standard output. > +`--trailer` option, if any, to each input file. The result is emitted on the > +standard output. > + > +This command can also operate on the output of linkgit:git-format-patch[1], > +which is more elaborate than a plain commit message. Namely, such output > +includes a commit message (as above), a "---" divider line, and a patch part. > +For these inputs, the divider and patch parts are ignored, unless `--no-divider` > +is specified. I think saying "the divider and patch parts are ignored" is a bit ambiguous. It could mean that when a patch is read by the command only its commit message, possibly modified by the command, is emitted on the standard output. I would suggest something like: "For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless `--no-divider` is specified."
