[v3,09/13] trailer --parse docs: add explanation for its usefulness

Commit Message

Linus Arver Sept. 7, 2023, 10:20 p.m. UTC

From: Linus Arver <[e-mail]>

For users who are skimming the docs to go straight to the individual
breakdown of each flag, it may not be clear why --parse is a convenience
alias (without them also looking at the other options that --parse turns
on). To save them the trouble of looking at the other options (and
computing what that would mean), describe a summary of the overall
effect.

Similarly update the area when we first mention --parse near the top of
the doc.

Signed-off-by: Linus Arver <[e-mail]>
---
 Documentation/git-interpret-trailers.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

Comments

Junio C Hamano Sept. 8, 2023, 9:57 p.m. UTC | #1

"Linus Arver via GitGitGadget" <[e-mail]> writes:

>  --parse::
>  	A convenience alias for `--only-trailers --only-input
> -	--unfold`.
> +	--unfold`. This makes it easier to only see the trailers coming from the
> +	input without influencing them with any command line options or
> +	configuration variables, while also making the output machine-friendly with
> +	--unfold.

Nicely explained.  Without a concise explanation like this, it is
hard to see what the value of the "convenience" alias actually is.

Patch

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 0eea937c30e..2d49445b1c3 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -31,7 +31,9 @@  the last two lines starting with "Signed-off-by" are 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.
+If `--parse` is specified, the output consists of the parsed trailers
+coming from the input, without influencing them with any command line
+options or configuration variables.
 Otherwise, this command applies the arguments passed using the
 `--trailer` option, if any, to each input file. The result is emitted on the
 standard output.
@@ -158,7 +160,10 @@  OPTIONS
 
 --parse::
 	A convenience alias for `--only-trailers --only-input
-	--unfold`.
+	--unfold`. This makes it easier to only see the trailers coming from the
+	input without influencing them with any command line options or
+	configuration variables, while also making the output machine-friendly with
+	--unfold.
 
 --no-divider::
 	Do not treat `---` as the end of the commit message. Use this