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

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

[kristofferhaugsbakk]

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:

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
-- 
2.55.0.793.gc667de3f2c5

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> 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.

> 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

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

[Kristoffer Haugsbakk]

On Mon, Sep 28, 2026, at 20:29, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>> 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.

I’ll make that change.

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

[kristofferhaugsbakk]

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.)

Steal how the `see` example is phrased and use that as a template:

    Configure a `see` trailer with a command to show the subject of a
    commit that is related, and show how it works:

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name (applied): kh/doc-trailers-cmd-examples
    
    v2:
    • *Steal* the *existing* example:
       https://lore.kernel.org/git/xmqqh5j9mdpx.fsf@gitster.g/

 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

Interdiff against v1:

Range-diff against v1:
1:  c916709d7a3 ! 1:  a8c56a91163 doc: interpret-trailers: fix cmd examples
    @@ Commit message
         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:
    +    Steal how the `see` example is phrased and use that as a template:
     
             Configure a `see` trailer with a command to show the subject of a
             commit that is related, and show how it works:

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.55.0.793.gc667de3f2c5

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> 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.)
>
> Steal how the `see` example is phrased and use that as a template:
>
>     Configure a `see` trailer with a command to show the subject of a
>     commit that is related, and show how it works:
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---

Let me mark the topic for 'next'.
Thanks.