Re: [PATCH] doc: interpret-trailers: fix cmd examples

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 28, 2026, 18:29 UTC
Message-ID: <xmqqh5j9mdpx.fsf@gitster.g>
In-Reply-To: <doc_trailers_cmd_examples.ce1@m5gid.xyz>

kristofferhaugsbakk@fastmail.com writes:

Show 10 quoted lines

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Fix `trailer.<key-alias>.cmd` examples which have remained unchanged
> since they were written in c364b7ef (trailer: add new .cmd config
> option, 2021-05-03). (Modulo formatting changes.)
>
> Use this example as a guide for how to phrase it:
>
>     Configure a `see` trailer with a command to show the subject of a
>     commit that is related, and show how it works:

This read as if you are declaring that you use a template that invented to consistently give intro for each example, and made it look like the use of `see` was as a placeholder. It would have avoided the "Huh?" reaction if it were phrased like so:

    Steal how example to show the `see` trailer is phrased and use
    it throughout:

	Configure a `see` trailer ...

Other than that, this looks good.

Show 39 quoted lines

> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> Notes (series):
>     Topic name: kh/doc-trailers-cmd-examples
>
>  Documentation/git-interpret-trailers.adoc | 10 ++++------
>  1 file changed, 4 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index 77b4f63b05c..3e81632b252 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -305,9 +305,8 @@ subject
>  Fix #42
>  ------------
>  
> -* Configure a `help` trailer with a cmd use a script `glog-find-author`
> -  which search specified author identity from git log in git repository
> -  and show how it works:
> +* Configure a `help` trailer with a command that searches for an author
> +  identity and show how it works:
>  +
>  ------------
>  $ cat ~/bin/glog-find-author
> @@ -329,9 +328,8 @@ Helped-by: Junio C Hamano <gitster@pobox.com>
>  Helped-by: Christian Couder <christian.couder@gmail.com>
>  ------------
>  
> -* Configure a `ref` trailer with a cmd use a script `glog-grep`
> -  to grep last relevant commit from git log in the git repository
> -  and show how it works:
> +* Configure a `ref` trailer with a command that searches for the last
> +  relevant commit and show how it works:
>  +
>  ------------
>  $ cat ~/bin/glog-grep
>
> base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc