[PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[Kristoffer Haugsbakk]

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e..787332771e 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -408,9 +408,9 @@ $ git config trailer.see.ifMissing "doNothing"
 $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
 $ git interpret-trailers <<EOF
 > subject
-> 
+>
 > message
-> 
+>
 > see: HEAD~2
 > EOF
 subject
@@ -429,9 +429,9 @@ See-also: fe3187489d69c4 (subject of related commit)
 ------------
 $ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
 > ***subject***
-> 
+>
 > ***message***
-> 
+>
 > Fixes: Z
 > Cc: Z
 > Reviewed-by: Z
-- 
2.40.0

[PATCH 2/3] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

`trailer.sign.command` has been deprecated since commit
c364b7ef51 (trailer: add new .cmd config option, 2021-05-03).

Use the commit message of c364b7ef51 as a guide to replace the use of
`$ARG` and to use a script instead of an inline command.[1] Also,
explicitly trigger the command by passing in `--trailer=sign`, since
this config is not automatically used.[2]

[1]: “Instead of "$ARG", users can refer to the value as positional
   argument, $1, in their scripts.”
[2]: “At the same time, in order to allow `git interpret-trailers` to
   better simulate the behavior of `git command -s`,
   'trailer.<token>.cmd' will not automatically execute.”

Cc: ZheNing Hu <adlternative@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 787332771e..792d61ae7b 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -325,7 +325,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
-$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
+$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
 $ git interpret-trailers <<EOF
 > EOF
 
@@ -402,11 +402,14 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
   commit that is related, and show how it works:
 +
 ------------
+$ cat ~/bin/glog-ref
+#!/bin/sh
+git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
-$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <<EOF
+$ git config trailer.see.cmd "glog-ref"
+$ git interpret-trailers --trailer=see <<EOF
 > subject
 >
 > message
-- 
2.40.0

[PATCH 3/3] doc: interpret-trailers: fix example

[Kristoffer Haugsbakk]

This command won’t output anything if you don’t give it an input and/or
a `--trailer`.

Cc: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 792d61ae7b..2aa190fd3f 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -326,7 +326,7 @@ $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers <<EOF
+$ git interpret-trailers --trailer sign <<EOF
 > EOF
 
 Signed-off-by: Bob <bob@example.com>
-- 
2.40.0

Re: [PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[Kristoffer Haugsbakk]

On Fri, Mar 31, 2023, at 20:12, Kristoffer Haugsbakk wrote:
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

It seems that my cover letter got denied since it contained non-ascii in the subject.

I’ll re-roll later.

-- 
Kristoffer Haugsbakk

Re: [PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[Kristoffer Haugsbakk]

On Fri, Mar 31, 2023, at 20:21, Kristoffer Haugsbakk wrote:
> I’ll re-roll later.

Interestingly though it worked for the third patch which had the same
subject since it got encoded properly. But I pasted in the same subject
manually in the cover letter.

-- 
Kristoffer Haugsbakk

Re: [PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

>  $ git interpret-trailers <<EOF
>  > subject
> -> 
> +>
>  > message
> -> 
> +>
>  > see: HEAD~2
>  > EOF
>  subject

This example pretends as if the above was an interactive session the
writer of the documentation did with a shell in a terminal, and
these lines are trying to show that each line is prefixed with $PS2
(the secondary prompt string given by the shell for continued
lines).

Taking that fact into account, it is arguably more correct to keep
these spaces rather than removing them like this patch does, but of
course it does not make a practical difference, because these spaces
are invisible unless the reader reads the source documentation pages
without passing them through AsciiDoc machinery.

The only folks that would be helped by this patch are those of us
who edit one of these four lines of the source file (perhaps by
replacing '>' with '|', such a patch tries to show use of a
different $PS2) and are annoyed to see trailing whitespaces their
patch inherited from the original trigger "git diff --check"; I
wonder if that is a good enough justification.

I, however, do wonder if we should make our example more friendly to
cutting and pasting.  And I would not mind it if we got rid of these
4 trailing whitespaces as a side effect of such an effort.

One way to do so, while still pretending to show an actual session
with an interactive shell, may be to give the example with an empty
string set to $PS2, i.e.

    $ git interpret-trailers <<\EOF
    subject

    message

    see: HEAD~2
    EOF
    subject
    ...

but then it makes it a bit harder to see what is input and what is
output.  Showing with a separate intermediate file, i.e.

    $ cat sample-message.txt
    subject

    message

    see: HEAD~2
    $ git interpret-trailers <sample-message.txt
    subject
    ...

might make the result slightly easier to follow.  I dunno.

The same comment applies to the other hunk.

Thanks.

Re: [PATCH 1/3] doc: interpret-trailers: remove trailing spaces

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

[jc: I forgot to cc the area expert, so here is a forward]

> Kristoffer Haugsbakk <code@khaugsbakk.name> writes:
>
>>  $ git interpret-trailers <<EOF
>>  > subject
>> -> 
>> +>
>>  > message
>> -> 
>> +>
>>  > see: HEAD~2
>>  > EOF
>>  subject
>
> This example pretends as if the above was an interactive session the
> writer of the documentation did with a shell in a terminal, and
> these lines are trying to show that each line is prefixed with $PS2
> (the secondary prompt string given by the shell for continued
> lines).
>
> Taking that fact into account, it is arguably more correct to keep
> these spaces rather than removing them like this patch does, but of
> course it does not make a practical difference, because these spaces
> are invisible unless the reader reads the source documentation pages
> without passing them through AsciiDoc machinery.
>
> The only folks that would be helped by this patch are those of us
> who edit one of these four lines of the source file (perhaps by
> replacing '>' with '|', such a patch tries to show use of a
> different $PS2) and are annoyed to see trailing whitespaces their
> patch inherited from the original trigger "git diff --check"; I
> wonder if that is a good enough justification.
>
> I, however, do wonder if we should make our example more friendly to
> cutting and pasting.  And I would not mind it if we got rid of these
> 4 trailing whitespaces as a side effect of such an effort.
>
> One way to do so, while still pretending to show an actual session
> with an interactive shell, may be to give the example with an empty
> string set to $PS2, i.e.
>
>     $ git interpret-trailers <<\EOF
>     subject
>
>     message
>
>     see: HEAD~2
>     EOF
>     subject
>     ...
>
> but then it makes it a bit harder to see what is input and what is
> output.  Showing with a separate intermediate file, i.e.
>
>     $ cat sample-message.txt
>     subject
>
>     message
>
>     see: HEAD~2
>     $ git interpret-trailers <sample-message.txt
>     subject
>     ...
>
> might make the result slightly easier to follow.  I dunno.
>
> The same comment applies to the other hunk.
>
> Thanks.

Re: [PATCH 2/3] doc: interpret-trailers: don’t use deprecated config

[Andrei Rybak]

I've noticed a discrepancy in this patch

On 31/03/2023 20:14, Kristoffer Haugsbakk wrote:
> explicitly trigger the command by passing in `--trailer=sign`, since

Commit message mentions "sign" as the value for "--trailer=" ...

> -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
> -$ git interpret-trailers <<EOF
> +$ git config trailer.see.cmd "glog-ref"
> +$ git interpret-trailers --trailer=see <<EOF

... but the new sample code uses "see" as the value.

>   > subject
>   >
>   > message

[PATCH v2 0/3] doc: interpret-trailers: don't use deprecated config

[Kristoffer Haugsbakk]

Replace deprecated `command` with `cmd` (patch 2). While visiting this
file also rewrite heredoc examples to use files which are shown with
cat(1) (patch 1) and fix two examples that didn’t work properly (patch
3).

§ Changes in v2

First of all I had to send a second version since I messed up sending my
v1 cover letter (unencoded Unicode in the subject). But I ended up doing
quite a few changes:

1. Patch 1: Junio had some alternative suggestions. Remove trailing
   spaces by using files which are shown with cat(1) and thereby make it
   easier to copy-paste from the docs.
2. Patch 2: Fix discrepancy (see/sign) in commit message (thanks to
   Andrei Rybak)
3. Patch 2: minor commit message correction
4. Patch 3: Fix another example and build on top of it by using the
   typical “subject/message” format instead of an empty file and an
   s-o-b file (a file with just an s-o-b trailer)

Kristoffer Haugsbakk (3):
  doc: interpret-trailers: don’t use heredoc in examples
  doc: interpret-trailers: don’t use deprecated config
  doc: interpret-trailers: fix examples

 Documentation/git-interpret-trailers.txt | 93 +++++++++++++-----------
 1 file changed, 52 insertions(+), 41 deletions(-)

Range-diff against v1:
1:  b57fac21e4 < -:  ---------- doc: interpret-trailers: remove trailing spaces
2:  d85e955ff2 < -:  ---------- doc: interpret-trailers: don’t use deprecated config
3:  bd6b78a707 < -:  ---------- doc: interpret-trailers: fix example
-:  ---------- > 1:  38f9a4bdf8 doc: interpret-trailers: don’t use heredoc in examples
-:  ---------- > 2:  ea06be8f5a doc: interpret-trailers: don’t use deprecated config
-:  ---------- > 3:  14555cf87f doc: interpret-trailers: fix examples
--
2.40.0

[PATCH v2 1/3] doc: interpret-trailers: don’t use heredoc in examples

[Kristoffer Haugsbakk]

This file contains four instances of trailing spaces from its inception
in commit [1]. These spaces might be intentional, since a user would be
prompted with `> ` in an interactive session. On the one hand, this is a
whitespace error according to `git diff --check`; on the other hand, the
raw documentation—it makes no difference in the rendered output—is just
staying faithful to the simulation of the interactive prompt.

Let’s get rid of these whitespace errors and also make the examples more
friendly to cut-and-paste by replacing the heredocs with files which are
shown with cat(1).

[1]: dfd66ddf5a (Documentation: add documentation for 'git
    interpret-trailers', 2014-10-13)

Suggested-by: Junio C Hamano <gitster@pobox.com>
Cc: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    This was one of the suggestions by Junio[1]
    
    > Showing with a separate intermediate file, i.e.
    > [snip]
    > might make the result slightly easier to follow.  I dunno.
    
    [1]: https://lore.kernel.org/git/xmqqsfdkep2b.fsf@gitster.g/

 Documentation/git-interpret-trailers.txt | 72 +++++++++++-------------
 1 file changed, 33 insertions(+), 39 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e..dbbb6815c3 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -326,13 +326,12 @@ $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers <<EOF
-> EOF
+$ cat empty-msg.txt | git interpret-trailers
 
 Signed-off-by: Bob <bob@example.com>
-$ git interpret-trailers <<EOF
-> Signed-off-by: Alice <alice@example.com>
-> EOF
+$ cat msg.txt
+Signed-off-by: Alice <alice@example.com>
+$ cat msg.txt | git interpret-trailers
 
 Signed-off-by: Alice <alice@example.com>
 ------------
@@ -357,15 +356,14 @@ Fix #42
 $ cat ~/bin/glog-find-author
 #!/bin/sh
 test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.help.key "Helped-by: "
 $ git config trailer.help.ifExists "addIfDifferentNeighbor"
 $ git config trailer.help.cmd "~/bin/glog-find-author"
-$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
-> subject
->
-> message
->
-> EOF
+$ cat msg.txt | git interpret-trailers --trailer="help:Junio" --trailer="help:Couder"
 subject
 
 message
@@ -382,15 +380,14 @@ Helped-by: Christian Couder <christian.couder@gmail.com>
 $ cat ~/bin/glog-grep
 #!/bin/sh
 test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.ref.key "Reference-to: "
 $ git config trailer.ref.ifExists "replace"
 $ git config trailer.ref.cmd "~/bin/glog-grep"
-$ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
-> subject
->
-> message
->
-> EOF
+$ cat msg.txt | git interpret-trailers --trailer="ref:Add copyright notices."
 subject
 
 message
@@ -402,17 +399,15 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
   commit that is related, and show how it works:
 +
 ------------
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
 $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <<EOF
-> subject
-> 
-> message
-> 
-> see: HEAD~2
-> EOF
+$ cat msg.txt | git interpret-trailers
 subject
 
 message
@@ -427,22 +422,21 @@ See-also: fe3187489d69c4 (subject of related commit)
   to add a 'git-version' trailer:
 +
 ------------
-$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
-> ***subject***
-> 
-> ***message***
-> 
-> Fixes: Z
-> Cc: Z
-> Reviewed-by: Z
-> Signed-off-by: Z
-> EOF
+$ cat commit_template.txt
+***subject***
+
+***message***
+
+Fixes: Z
+Cc: Z
+Reviewed-by: Z
+Signed-off-by: Z
+$ sed --in-place -e 's/ Z$/ /' commit_template.txt
 $ git config commit.template commit_template.txt
-$ cat >.git/hooks/commit-msg <<EOF
-> #!/bin/sh
-> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
-> mv "\$1.new" "\$1"
-> EOF
+$ cat .git/hooks/commit-msg
+#!/bin/sh
+git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
+mv "\$1.new" "\$1"
 $ chmod +x .git/hooks/commit-msg
 ------------
 
-- 
2.40.0

[PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

`command` has been deprecated since commit c364b7ef51 (trailer: add new
.cmd config option, 2021-05-03).

Use the commit message of c364b7ef51 as a guide to replace the use of
`$ARG` and to use a script instead of an inline command.[1] Also,
explicitly trigger the command by passing in `--trailer=see`, since
this config is not automatically used.[2]

[1]: “Instead of "$ARG", users can refer to the value as positional
   argument, $1, in their scripts.”
[2]: “At the same time, in order to allow `git interpret-trailers` to
   better simulate the behavior of `git command -s`,
   'trailer.<token>.cmd' will not automatically execute.”

Cc: ZheNing Hu <adlternative@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index dbbb6815c3..c76efae76a 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -325,7 +325,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
-$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
+$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
 $ cat empty-msg.txt | git interpret-trailers
 
 Signed-off-by: Bob <bob@example.com>
@@ -403,11 +403,14 @@ $ cat msg.txt
 subject
 
 message
+$ cat ~/bin/glog-ref
+#!/bin/sh
+git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
-$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ cat msg.txt | git interpret-trailers
+$ git config trailer.see.cmd "glog-ref"
+$ cat msg.txt | git interpret-trailers --trailer=see
 subject
 
 message
-- 
2.40.0

[PATCH v2 3/3] doc: interpret-trailers: fix examples

[Kristoffer Haugsbakk]

We need to provide `--trailer sign` since the command won’t output
anything if you don’t give it an input and/or a
`--trailer`. Furthermore, the example where `msg.txt` already contains
an s-o-b is wrong:

    $ cat msg.txt | git interpret-trailers --trailer sign
    Signed-off-by: Alice <alice@example.com>

    Signed-off-by: Alice <alice@example.com>

A file which only consists of one trailer line is not interpreted as the
original example must have expected. So change the examples to use the
typical “subject/message” file.

Cc: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    This isn’t just a quirk of this series but also happens on `master`:
    
        $ git config trailer.sign.ifmissing add
        $ git config trailer.sign.ifexists doNothing
        $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
        $ git interpret-trailers <<EOF
        > EOF
        $ git interpret-trailers <<EOF
        Signed-off-by: Alice <alice@example.com>
        > EOF
        Signed-off-by: Alice <alice@example.com>
    
        Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

 Documentation/git-interpret-trailers.txt | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index c76efae76a..c6f5b92ecc 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -322,16 +322,30 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
   'Signed-off-by: ' already, and show how it works:
 +
 ------------
+$ cat msg1.txt
+subject
+
+message
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
-$ cat empty-msg.txt | git interpret-trailers
+$ cat msg1.txt | git interpret-trailers --trailer sign
+subject
+
+message
 
 Signed-off-by: Bob <bob@example.com>
-$ cat msg.txt
+$ cat msg2.txt
+subject
+
+message
+
 Signed-off-by: Alice <alice@example.com>
-$ cat msg.txt | git interpret-trailers
+$ cat msg2.txt | git interpret-trailers --trailer sign
+subject
+
+message
 
 Signed-off-by: Alice <alice@example.com>
 ------------
-- 
2.40.0

Re: [PATCH v2 1/3] doc: interpret-trailers: don’t use heredoc in examples

[Junio C Hamano]

> @@ -357,15 +356,14 @@ Fix #42
>  $ cat ~/bin/glog-find-author
>  #!/bin/sh
>  test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
> +$ cat msg.txt
> +subject
> +
> +message

When I suggested to use "cat" to show contents, instead of
pretending an interactive session, I didn't check if we already had
examples, but it looks like we did, which is great.

> +$ cat msg.txt | git interpret-trailers --trailer="help:Junio" --trailer="help:Couder"

Do not "cat" a single file and pipe into another command.  It will
always be equivalent to redirecting that file into the command on
the downstream, i.e.

   $ git interpret-trailers --options <mst.txt

> +$ sed --in-place -e 's/ Z$/ /' commit_template.txt

Avoid "--in-place"; not everybody's "sed" has it.

Other than that, I didn't spot anything glaringly wrong.

Thanks for working on this series.

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

> [2]: “At the same time, in order to allow `git interpret-trailers` to
>    better simulate the behavior of `git command -s`,
>    'trailer.<token>.cmd' will not automatically execute.”

This may be a question more for Zhening than for you, but is the
above a typo for "git commit -s", not "command"?

> +$ git config trailer.see.cmd "glog-ref"
> +$ cat msg.txt | git interpret-trailers --trailer=see

This is inherited from the original, but it is a poor practice to
run "cat" on a single file and pipe the result to another command.
Just redirect from the file into the downstream command instead,
i.e.

    $ git interpret-trailers <empty-msg.txt

Perhaps we should do that as a preliminary clean-up before these
updates?

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

On Mon, Apr 3, 2023, at 23:18, Junio C Hamano wrote:
> Perhaps we should do that as a preliminary clean-up before these
> updates?

I think updating to use `<msg.txt` for existing (on `master`) examples
would fit in as patch number 2, since I rewrite heredocs to use files in
patch 1. The commit message for patch 2 would then say, “and let’s make
things consistent for the other examples as well”.

Thanks for spotting that. :)

-- 
Kristoffer Haugsbakk

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Mon, Apr 3, 2023, at 23:18, Junio C Hamano wrote:
>> Perhaps we should do that as a preliminary clean-up before these
>> updates?
>
> I think updating to use `<msg.txt` for existing (on `master`) examples
> would fit in as patch number 2, since I rewrite heredocs to use files in
> patch 1. The commit message for patch 2 would then say, “and let’s make
> things consistent for the other examples as well”.

The suggestion to do so in a separate preliminary step was made
because I had an impression that existing examples were full of
these "cat file | command" patterns, and you were adjusting only
some of them.  If there were (I didn't count or re-check the file)
say 10 such bad examples and you are only changing only two for the
primary purpose of the patch (i.e. use interpret-trailers command
correctly), updating the other 8 bad examples "while at it" would
make the patch with unnecessarily noisy, and fixing the "cat file |"
in a separate step may help us let each step of the series focus on
one thing and do it well.

But I see there is only one or two existing "cat file | command", so
I agree with you that it is more reasonable to do it there.

Thanks.

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[ZheNing Hu]

Kristoffer Haugsbakk <code@khaugsbakk.name> 于2023年4月4日周二 03:24写道：
>
> `command` has been deprecated since commit c364b7ef51 (trailer: add new
> .cmd config option, 2021-05-03).
>
> Use the commit message of c364b7ef51 as a guide to replace the use of
> `$ARG` and to use a script instead of an inline command.[1] Also,
> explicitly trigger the command by passing in `--trailer=see`, since
> this config is not automatically used.[2]
>
> [1]: “Instead of "$ARG", users can refer to the value as positional
>    argument, $1, in their scripts.”
> [2]: “At the same time, in order to allow `git interpret-trailers` to
>    better simulate the behavior of `git command -s`,
>    'trailer.<token>.cmd' will not automatically execute.”
>

Changing these examples from command -> cmd makes sense.
So users will tend to use 'cmd' instead of 'command' as much as
possible when referring to examples.

> Cc: ZheNing Hu <adlternative@gmail.com>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-interpret-trailers.txt | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index dbbb6815c3..c76efae76a 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -325,7 +325,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
>  $ git config trailer.sign.key "Signed-off-by: "
>  $ git config trailer.sign.ifmissing add
>  $ git config trailer.sign.ifexists doNothing
> -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
> +$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
>  $ cat empty-msg.txt | git interpret-trailers
>
>  Signed-off-by: Bob <bob@example.com>
> @@ -403,11 +403,14 @@ $ cat msg.txt
>  subject
>
>  message
> +$ cat ~/bin/glog-ref
> +#!/bin/sh
> +git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
>  $ git config trailer.see.key "See-also: "
>  $ git config trailer.see.ifExists "replace"
>  $ git config trailer.see.ifMissing "doNothing"
> -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
> -$ cat msg.txt | git interpret-trailers
> +$ git config trailer.see.cmd "glog-ref"
> +$ cat msg.txt | git interpret-trailers --trailer=see
>  subject
>
>  message
> --
> 2.40.0
>

Thanks.
--
ZheNing Hu

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[ZheNing Hu]

Junio C Hamano <gitster@pobox.com> 于2023年4月4日周二 05:18写道：
>
> Kristoffer Haugsbakk <code@khaugsbakk.name> writes:
>
> > [2]: “At the same time, in order to allow `git interpret-trailers` to
> >    better simulate the behavior of `git command -s`,
> >    'trailer.<token>.cmd' will not automatically execute.”
>
> This may be a question more for Zhening than for you, but is the
> above a typo for "git commit -s", not "command"?
>

Ah, indeed it was a typo.

> > +$ git config trailer.see.cmd "glog-ref"
> > +$ cat msg.txt | git interpret-trailers --trailer=see
>
> This is inherited from the original, but it is a poor practice to
> run "cat" on a single file and pipe the result to another command.
> Just redirect from the file into the downstream command instead,
> i.e.
>
>     $ git interpret-trailers <empty-msg.txt
>
> Perhaps we should do that as a preliminary clean-up before these
> updates?

Re: [PATCH v2 2/3] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

On Wed, Apr 5, 2023, at 09:45, ZheNing Hu wrote:
> Changing these examples from command -> cmd makes sense.
> So users will tend to use 'cmd' instead of 'command' as much as
> possible when referring to examples.

Thanks ZheNing. I’ll add an “ack” trailer to this patch. :)

-- 
Kristoffer Haugsbakk

[PATCH v3 0/4] doc: interpret-trailers: don't use deprecated config

[Kristoffer Haugsbakk]

Replace deprecated `command` with `cmd` (patch 3). While visiting this
file also:

• rewrite heredoc examples to use files which are shown with
  cat(1) (patch 1);
• use input redirection instead of using cat(1) piped into `git
  interpret-trailers` (patch 2); and
• fix an example that didn’t work properly (patch 4).

§ Changes in v3

• All patches: drop “Cc” trailers
• Patch 1: Use input redirection instead of `cat msg.txt | git […]`
• Patch 2: New
• Patch 3: Add “acked” trailer
• Patch 4: Tweak commit message

Kristoffer Haugsbakk (4):
  doc: interpret-trailers: don’t use heredoc in examples
  doc: interpret-trailers: use input redirection
  doc: interpret-trailers: don’t use deprecated config
  doc: interpret-trailers: fix example

 Documentation/git-interpret-trailers.txt | 97 ++++++++++++++----------
 1 file changed, 55 insertions(+), 42 deletions(-)

Range-diff against v2:
1:  38f9a4bdf8 ! 1:  fd515ad8b4 doc: interpret-trailers: don’t use heredoc in examples
    @@ Commit message
             interpret-trailers', 2014-10-13)

         Suggested-by: Junio C Hamano <gitster@pobox.com>
    -    Cc: Christian Couder <chriscool@tuxfamily.org>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

    -
    - ## Notes (series) ##
    -    This was one of the suggestions by Junio[1]
    -
    -    > Showing with a separate intermediate file, i.e.
    -    > [snip]
    -    > might make the result slightly easier to follow.  I dunno.
    -
    -    [1]: https://lore.kernel.org/git/xmqqsfdkep2b.fsf@gitster.g/
    -
      ## Documentation/git-interpret-trailers.txt ##
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.key "Signed-off-by: "
      $ git config trailer.sign.ifmissing add
    @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.key "Signed-
      $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
     -$ git interpret-trailers <<EOF
     -> EOF
    -+$ cat empty-msg.txt | git interpret-trailers
    ++$ git interpret-trailers <empty-msg.txt

      Signed-off-by: Bob <bob@example.com>
     -$ git interpret-trailers <<EOF
    @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.key "Signed-
     -> EOF
     +$ cat msg.txt
     +Signed-off-by: Alice <alice@example.com>
    -+$ cat msg.txt | git interpret-trailers
    ++$ git interpret-trailers <msg.txt

      Signed-off-by: Alice <alice@example.com>
      ------------
    @@ Documentation/git-interpret-trailers.txt: Fix #42
     -> message
     ->
     -> EOF
    -+$ cat msg.txt | git interpret-trailers --trailer="help:Junio" --trailer="help:Couder"
    ++$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
      subject

      message
    @@ Documentation/git-interpret-trailers.txt: Helped-by: Christian Couder <christian
     -> message
     ->
     -> EOF
    -+$ cat msg.txt | git interpret-trailers --trailer="ref:Add copyright notices."
    ++$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
      subject

      message
    @@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh
     +subject
     +
     +message
    ++
    ++see: HEAD~2
      $ git config trailer.see.key "See-also: "
      $ git config trailer.see.ifExists "replace"
      $ git config trailer.see.ifMissing "doNothing"
    @@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh
     ->
     -> see: HEAD~2
     -> EOF
    -+$ cat msg.txt | git interpret-trailers
    ++$ git interpret-trailers <msg.txt
      subject

      message
    @@ Documentation/git-interpret-trailers.txt: See-also: fe3187489d69c4 (subject of r
     -> Reviewed-by: Z
     -> Signed-off-by: Z
     -> EOF
    -+$ cat commit_template.txt
    ++$ cat temp.txt
     +***subject***
     +
     +***message***
    @@ Documentation/git-interpret-trailers.txt: See-also: fe3187489d69c4 (subject of r
     +Cc: Z
     +Reviewed-by: Z
     +Signed-off-by: Z
    -+$ sed --in-place -e 's/ Z$/ /' commit_template.txt
    ++$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
      $ git config commit.template commit_template.txt
     -$ cat >.git/hooks/commit-msg <<EOF
     -> #!/bin/sh
-:  ---------- > 2:  12f7b10462 doc: interpret-trailers: use input redirection
2:  ea06be8f5a ! 3:  dc1982f0d0 doc: interpret-trailers: don’t use deprecated config
    @@ Commit message
            better simulate the behavior of `git command -s`,
            'trailer.<token>.cmd' will not automatically execute.”

    -    Cc: ZheNing Hu <adlternative@gmail.com>
    +    Acked-by: ZheNing Hu <adlternative@gmail.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

      ## Documentation/git-interpret-trailers.txt ##
    @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
      $ git config trailer.sign.ifexists doNothing
     -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
     +$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
    - $ cat empty-msg.txt | git interpret-trailers
    + $ git interpret-trailers <empty-msg.txt

      Signed-off-by: Bob <bob@example.com>
    -@@ Documentation/git-interpret-trailers.txt: $ cat msg.txt
    - subject
    -
    +@@ Documentation/git-interpret-trailers.txt: subject
      message
    +
    + see: HEAD~2
     +$ cat ~/bin/glog-ref
     +#!/bin/sh
     +git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
    @@ Documentation/git-interpret-trailers.txt: $ cat msg.txt
      $ git config trailer.see.ifExists "replace"
      $ git config trailer.see.ifMissing "doNothing"
     -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
    --$ cat msg.txt | git interpret-trailers
    +-$ git interpret-trailers <msg.txt
     +$ git config trailer.see.cmd "glog-ref"
    -+$ cat msg.txt | git interpret-trailers --trailer=see
    ++$ git interpret-trailers --trailer=see <msg.txt
      subject

      message
3:  14555cf87f ! 4:  f6e5605107 doc: interpret-trailers: fix examples
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>

      ## Commit message ##
    -    doc: interpret-trailers: fix examples
    +    doc: interpret-trailers: fix example

         We need to provide `--trailer sign` since the command won’t output
         anything if you don’t give it an input and/or a
    -    `--trailer`. Furthermore, the example where `msg.txt` already contains
    -    an s-o-b is wrong:
    +    `--trailer`. Furthermore, the message which already contains an s-o-b is
    +    wrong:

    -        $ cat msg.txt | git interpret-trailers --trailer sign
    +        $ git interpret-trailers --trailer sign <msg.txt
             Signed-off-by: Alice <alice@example.com>

             Signed-off-by: Alice <alice@example.com>

    -    A file which only consists of one trailer line is not interpreted as the
    -    original example must have expected. So change the examples to use the
    -    typical “subject/message” file.
    -
    -    Cc: Christian Couder <chriscool@tuxfamily.org>
    -    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    +    This can’t be what was originally intended.

    +    So change the messages in this example to use the typical
    +    “subject/message” file.

    - ## Notes (series) ##
    -    This isn’t just a quirk of this series but also happens on `master`:
    -
    -        $ git config trailer.sign.ifmissing add
    -        $ git config trailer.sign.ifexists doNothing
    -        $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
    -        $ git interpret-trailers <<EOF
    -        > EOF
    -        $ git interpret-trailers <<EOF
    -        Signed-off-by: Alice <alice@example.com>
    -        > EOF
    -        Signed-off-by: Alice <alice@example.com>
    -
    -        Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    +    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>

      ## Documentation/git-interpret-trailers.txt ##
     @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
    @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
      $ git config trailer.sign.ifmissing add
      $ git config trailer.sign.ifexists doNothing
      $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
    --$ cat empty-msg.txt | git interpret-trailers
    -+$ cat msg1.txt | git interpret-trailers --trailer sign
    +-$ git interpret-trailers <empty-msg.txt
    ++$ git interpret-trailers --trailer sign <msg1.txt
     +subject
     +
     +message
    @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
     +message
     +
      Signed-off-by: Alice <alice@example.com>
    --$ cat msg.txt | git interpret-trailers
    -+$ cat msg2.txt | git interpret-trailers --trailer sign
    +-$ git interpret-trailers <msg.txt
    ++$ git interpret-trailers --trailer sign <msg2.txt
     +subject
     +
     +message
--
2.40.0

[PATCH v3 1/4] doc: interpret-trailers: don’t use heredoc in examples

[Kristoffer Haugsbakk]

This file contains four instances of trailing spaces from its inception
in commit [1]. These spaces might be intentional, since a user would be
prompted with `> ` in an interactive session. On the one hand, this is a
whitespace error according to `git diff --check`; on the other hand, the
raw documentation—it makes no difference in the rendered output—is just
staying faithful to the simulation of the interactive prompt.

Let’s get rid of these whitespace errors and also make the examples more
friendly to cut-and-paste by replacing the heredocs with files which are
shown with cat(1).

[1]: dfd66ddf5a (Documentation: add documentation for 'git
    interpret-trailers', 2014-10-13)

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 74 +++++++++++-------------
 1 file changed, 35 insertions(+), 39 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e..15d34b983f 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -326,13 +326,12 @@ $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers <<EOF
-> EOF
+$ git interpret-trailers <empty-msg.txt
 
 Signed-off-by: Bob <bob@example.com>
-$ git interpret-trailers <<EOF
-> Signed-off-by: Alice <alice@example.com>
-> EOF
+$ cat msg.txt
+Signed-off-by: Alice <alice@example.com>
+$ git interpret-trailers <msg.txt
 
 Signed-off-by: Alice <alice@example.com>
 ------------
@@ -357,15 +356,14 @@ Fix #42
 $ cat ~/bin/glog-find-author
 #!/bin/sh
 test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.help.key "Helped-by: "
 $ git config trailer.help.ifExists "addIfDifferentNeighbor"
 $ git config trailer.help.cmd "~/bin/glog-find-author"
-$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
-> subject
->
-> message
->
-> EOF
+$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
 subject
 
 message
@@ -382,15 +380,14 @@ Helped-by: Christian Couder <christian.couder@gmail.com>
 $ cat ~/bin/glog-grep
 #!/bin/sh
 test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.ref.key "Reference-to: "
 $ git config trailer.ref.ifExists "replace"
 $ git config trailer.ref.cmd "~/bin/glog-grep"
-$ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
-> subject
->
-> message
->
-> EOF
+$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
 subject
 
 message
@@ -402,17 +399,17 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
   commit that is related, and show how it works:
 +
 ------------
+$ cat msg.txt
+subject
+
+message
+
+see: HEAD~2
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
 $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <<EOF
-> subject
-> 
-> message
-> 
-> see: HEAD~2
-> EOF
+$ git interpret-trailers <msg.txt
 subject
 
 message
@@ -427,22 +424,21 @@ See-also: fe3187489d69c4 (subject of related commit)
   to add a 'git-version' trailer:
 +
 ------------
-$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
-> ***subject***
-> 
-> ***message***
-> 
-> Fixes: Z
-> Cc: Z
-> Reviewed-by: Z
-> Signed-off-by: Z
-> EOF
+$ cat temp.txt
+***subject***
+
+***message***
+
+Fixes: Z
+Cc: Z
+Reviewed-by: Z
+Signed-off-by: Z
+$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
 $ git config commit.template commit_template.txt
-$ cat >.git/hooks/commit-msg <<EOF
-> #!/bin/sh
-> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
-> mv "\$1.new" "\$1"
-> EOF
+$ cat .git/hooks/commit-msg
+#!/bin/sh
+git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
+mv "\$1.new" "\$1"
 $ chmod +x .git/hooks/commit-msg
 ------------
 
-- 
2.40.0

[PATCH v3 2/4] doc: interpret-trailers: use input redirection

[Kristoffer Haugsbakk]

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Link: https://lore.kernel.org/git/xmqqbkk44qbo.fsf@gitster.g/

 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 15d34b983f..6b712564a4 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -280,7 +280,7 @@ $ cat msg.txt
 subject
 
 message
-$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
+$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
 subject
 
 message
-- 
2.40.0

[PATCH v3 3/4] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

`command` has been deprecated since commit c364b7ef51 (trailer: add new
.cmd config option, 2021-05-03).

Use the commit message of c364b7ef51 as a guide to replace the use of
`$ARG` and to use a script instead of an inline command.[1] Also,
explicitly trigger the command by passing in `--trailer=see`, since
this config is not automatically used.[2]

[1]: “Instead of "$ARG", users can refer to the value as positional
   argument, $1, in their scripts.”
[2]: “At the same time, in order to allow `git interpret-trailers` to
   better simulate the behavior of `git command -s`,
   'trailer.<token>.cmd' will not automatically execute.”

Acked-by: ZheNing Hu <adlternative@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 6b712564a4..d2a23e9161 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -325,7 +325,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
-$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
+$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
 $ git interpret-trailers <empty-msg.txt
 
 Signed-off-by: Bob <bob@example.com>
@@ -405,11 +405,14 @@ subject
 message
 
 see: HEAD~2
+$ cat ~/bin/glog-ref
+#!/bin/sh
+git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
-$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <msg.txt
+$ git config trailer.see.cmd "glog-ref"
+$ git interpret-trailers --trailer=see <msg.txt
 subject
 
 message
-- 
2.40.0

[PATCH v3 4/4] doc: interpret-trailers: fix example

[Kristoffer Haugsbakk]

We need to provide `--trailer sign` since the command won’t output
anything if you don’t give it an input and/or a
`--trailer`. Furthermore, the message which already contains an s-o-b is
wrong:

    $ git interpret-trailers --trailer sign <msg.txt
    Signed-off-by: Alice <alice@example.com>

    Signed-off-by: Alice <alice@example.com>

This can’t be what was originally intended.

So change the messages in this example to use the typical
“subject/message” file.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index d2a23e9161..4b97f812be 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -322,16 +322,30 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
   'Signed-off-by: ' already, and show how it works:
 +
 ------------
+$ cat msg1.txt
+subject
+
+message
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers <empty-msg.txt
+$ git interpret-trailers --trailer sign <msg1.txt
+subject
+
+message
 
 Signed-off-by: Bob <bob@example.com>
-$ cat msg.txt
+$ cat msg2.txt
+subject
+
+message
+
 Signed-off-by: Alice <alice@example.com>
-$ git interpret-trailers <msg.txt
+$ git interpret-trailers --trailer sign <msg2.txt
+subject
+
+message
 
 Signed-off-by: Alice <alice@example.com>
 ------------
-- 
2.40.0

Re: [PATCH v3 0/4] doc: interpret-trailers: don't use deprecated config

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

> Replace deprecated `command` with `cmd` (patch 3). While visiting this
> file also:
>
> • rewrite heredoc examples to use files which are shown with
>   cat(1) (patch 1);
> • use input redirection instead of using cat(1) piped into `git
>   interpret-trailers` (patch 2); and
> • fix an example that didn’t work properly (patch 4).

This was a pleasant read.  I had small nits here and there but
overall the series is very well crafted.

Will queue.  Thanks.

Re: [PATCH v3 2/4] doc: interpret-trailers: use input redirection

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

> Suggested-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---

Perhaps explain why it is a good idea in the body of the message?

    Instead of "cat"ting a single file into a pipe, redirect from
    the file to the standard input of the command on the downstream
    side of the pipe.  This is more straight-forward, saves one
    extra process, and often makes the line shorter.

or something like that.

Re: [PATCH v3 1/4] doc: interpret-trailers: don’t use heredoc in examples

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

> Let’s get rid of these whitespace errors and also make the examples more
> friendly to cut-and-paste by replacing the heredocs with files which are
> shown with cat(1).
> -$ git interpret-trailers <<EOF
> -> EOF
> +$ git interpret-trailers <empty-msg.txt
>  
>  Signed-off-by: Bob <bob@example.com>

Nobody created empty-msg.txt and readers need to guess that it is a
file with 0-byte contents.  Using "</dev/null" would have avoided
the need for guessing.

But it seems that this goes away at the end of the series, so let's
not worry too much about it ;-)

[PATCH v4 0/4] doc: interpret-trailers: don't use deprecated config

[Kristoffer Haugsbakk]

Replace deprecated `command` with `cmd` (patch 3). While visiting this
file also:

• rewrite heredoc examples to use files which are shown with
  cat(1) (patch 1);
• use input redirection instead of using cat(1) piped into `git
  interpret-trailers` (patch 2); and
• fix an example that didn’t work properly (patch 4).

§ Changes in v4

• Patch 1: Use `/dev/null` instead of `empty-msg.txt`
• Patch 2: Expand commit message

Kristoffer Haugsbakk (4):
  doc: interpret-trailers: don’t use heredoc in examples
  doc: interpret-trailers: use input redirection
  doc: interpret-trailers: don’t use deprecated config
  doc: interpret-trailers: fix example

 Documentation/git-interpret-trailers.txt | 97 ++++++++++++++----------
 1 file changed, 55 insertions(+), 42 deletions(-)

Range-diff against v3:
1:  fd515ad8b4 ! 1:  149dcf964c doc: interpret-trailers: don’t use heredoc in examples
    @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.key "Signed-
      $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
     -$ git interpret-trailers <<EOF
     -> EOF
    -+$ git interpret-trailers <empty-msg.txt
    ++$ git interpret-trailers </dev/null

      Signed-off-by: Bob <bob@example.com>
     -$ git interpret-trailers <<EOF
2:  12f7b10462 ! 2:  32483aa635 doc: interpret-trailers: use input redirection
    @@ Metadata
      ## Commit message ##
         doc: interpret-trailers: use input redirection

    +    Use input redirection instead of invoking cat(1) on a single file. This
    +    is more straightforward, saves a process, and often makes the line
    +    shorter.
    +
         Suggested-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>


      ## Notes (series) ##
    -    Link: https://lore.kernel.org/git/xmqqbkk44qbo.fsf@gitster.g/
    +    Junio suggested expanding the commit message:
    +    https://lore.kernel.org/git/xmqqjzyg7qdw.fsf@gitster.g/

      ## Documentation/git-interpret-trailers.txt ##
     @@ Documentation/git-interpret-trailers.txt: $ cat msg.txt
3:  dc1982f0d0 ! 3:  9ea4c4f916 doc: interpret-trailers: don’t use deprecated config
    @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
      $ git config trailer.sign.ifexists doNothing
     -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
     +$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
    - $ git interpret-trailers <empty-msg.txt
    + $ git interpret-trailers </dev/null

      Signed-off-by: Bob <bob@example.com>
     @@ Documentation/git-interpret-trailers.txt: subject
4:  f6e5605107 ! 4:  95760aafe8 doc: interpret-trailers: fix example
    @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
      $ git config trailer.sign.ifmissing add
      $ git config trailer.sign.ifexists doNothing
      $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
    --$ git interpret-trailers <empty-msg.txt
    +-$ git interpret-trailers </dev/null
     +$ git interpret-trailers --trailer sign <msg1.txt
     +subject
     +
--
2.40.1

[PATCH v4 1/4] doc: interpret-trailers: don’t use heredoc in examples

[Kristoffer Haugsbakk]

This file contains four instances of trailing spaces from its inception
in commit [1]. These spaces might be intentional, since a user would be
prompted with `> ` in an interactive session. On the one hand, this is a
whitespace error according to `git diff --check`; on the other hand, the
raw documentation—it makes no difference in the rendered output—is just
staying faithful to the simulation of the interactive prompt.

Let’s get rid of these whitespace errors and also make the examples more
friendly to cut-and-paste by replacing the heredocs with files which are
shown with cat(1).

[1]: dfd66ddf5a (Documentation: add documentation for 'git
    interpret-trailers', 2014-10-13)

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 74 +++++++++++-------------
 1 file changed, 35 insertions(+), 39 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e..4f4eb7a7fc 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -326,13 +326,12 @@ $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers <<EOF
-> EOF
+$ git interpret-trailers </dev/null
 
 Signed-off-by: Bob <bob@example.com>
-$ git interpret-trailers <<EOF
-> Signed-off-by: Alice <alice@example.com>
-> EOF
+$ cat msg.txt
+Signed-off-by: Alice <alice@example.com>
+$ git interpret-trailers <msg.txt
 
 Signed-off-by: Alice <alice@example.com>
 ------------
@@ -357,15 +356,14 @@ Fix #42
 $ cat ~/bin/glog-find-author
 #!/bin/sh
 test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.help.key "Helped-by: "
 $ git config trailer.help.ifExists "addIfDifferentNeighbor"
 $ git config trailer.help.cmd "~/bin/glog-find-author"
-$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
-> subject
->
-> message
->
-> EOF
+$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
 subject
 
 message
@@ -382,15 +380,14 @@ Helped-by: Christian Couder <christian.couder@gmail.com>
 $ cat ~/bin/glog-grep
 #!/bin/sh
 test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
+$ cat msg.txt
+subject
+
+message
 $ git config trailer.ref.key "Reference-to: "
 $ git config trailer.ref.ifExists "replace"
 $ git config trailer.ref.cmd "~/bin/glog-grep"
-$ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
-> subject
->
-> message
->
-> EOF
+$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
 subject
 
 message
@@ -402,17 +399,17 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
   commit that is related, and show how it works:
 +
 ------------
+$ cat msg.txt
+subject
+
+message
+
+see: HEAD~2
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
 $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <<EOF
-> subject
-> 
-> message
-> 
-> see: HEAD~2
-> EOF
+$ git interpret-trailers <msg.txt
 subject
 
 message
@@ -427,22 +424,21 @@ See-also: fe3187489d69c4 (subject of related commit)
   to add a 'git-version' trailer:
 +
 ------------
-$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
-> ***subject***
-> 
-> ***message***
-> 
-> Fixes: Z
-> Cc: Z
-> Reviewed-by: Z
-> Signed-off-by: Z
-> EOF
+$ cat temp.txt
+***subject***
+
+***message***
+
+Fixes: Z
+Cc: Z
+Reviewed-by: Z
+Signed-off-by: Z
+$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
 $ git config commit.template commit_template.txt
-$ cat >.git/hooks/commit-msg <<EOF
-> #!/bin/sh
-> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
-> mv "\$1.new" "\$1"
-> EOF
+$ cat .git/hooks/commit-msg
+#!/bin/sh
+git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
+mv "\$1.new" "\$1"
 $ chmod +x .git/hooks/commit-msg
 ------------
 
-- 
2.40.1

[PATCH v4 2/4] doc: interpret-trailers: use input redirection

[Kristoffer Haugsbakk]

Use input redirection instead of invoking cat(1) on a single file. This
is more straightforward, saves a process, and often makes the line
shorter.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Junio suggested expanding the commit message:
    https://lore.kernel.org/git/xmqqjzyg7qdw.fsf@gitster.g/

 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 4f4eb7a7fc..4ff8be7f2e 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -280,7 +280,7 @@ $ cat msg.txt
 subject
 
 message
-$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
+$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
 subject
 
 message
-- 
2.40.1

[PATCH v4 3/4] doc: interpret-trailers: don’t use deprecated config

[Kristoffer Haugsbakk]

`command` has been deprecated since commit c364b7ef51 (trailer: add new
.cmd config option, 2021-05-03).

Use the commit message of c364b7ef51 as a guide to replace the use of
`$ARG` and to use a script instead of an inline command.[1] Also,
explicitly trigger the command by passing in `--trailer=see`, since
this config is not automatically used.[2]

[1]: “Instead of "$ARG", users can refer to the value as positional
   argument, $1, in their scripts.”
[2]: “At the same time, in order to allow `git interpret-trailers` to
   better simulate the behavior of `git command -s`,
   'trailer.<token>.cmd' will not automatically execute.”

Acked-by: ZheNing Hu <adlternative@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 4ff8be7f2e..acecc037ec 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -325,7 +325,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
-$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
+$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
 $ git interpret-trailers </dev/null
 
 Signed-off-by: Bob <bob@example.com>
@@ -405,11 +405,14 @@ subject
 message
 
 see: HEAD~2
+$ cat ~/bin/glog-ref
+#!/bin/sh
+git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
 $ git config trailer.see.key "See-also: "
 $ git config trailer.see.ifExists "replace"
 $ git config trailer.see.ifMissing "doNothing"
-$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
-$ git interpret-trailers <msg.txt
+$ git config trailer.see.cmd "glog-ref"
+$ git interpret-trailers --trailer=see <msg.txt
 subject
 
 message
-- 
2.40.1

[PATCH v4 4/4] doc: interpret-trailers: fix example

[Kristoffer Haugsbakk]

We need to provide `--trailer sign` since the command won’t output
anything if you don’t give it an input and/or a
`--trailer`. Furthermore, the message which already contains an s-o-b is
wrong:

    $ git interpret-trailers --trailer sign <msg.txt
    Signed-off-by: Alice <alice@example.com>

    Signed-off-by: Alice <alice@example.com>

This can’t be what was originally intended.

So change the messages in this example to use the typical
“subject/message” file.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-interpret-trailers.txt | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index acecc037ec..4b97f812be 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -322,16 +322,30 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
   'Signed-off-by: ' already, and show how it works:
 +
 ------------
+$ cat msg1.txt
+subject
+
+message
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
 $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers </dev/null
+$ git interpret-trailers --trailer sign <msg1.txt
+subject
+
+message
 
 Signed-off-by: Bob <bob@example.com>
-$ cat msg.txt
+$ cat msg2.txt
+subject
+
+message
+
 Signed-off-by: Alice <alice@example.com>
-$ git interpret-trailers <msg.txt
+$ git interpret-trailers --trailer sign <msg2.txt
+subject
+
+message
 
 Signed-off-by: Alice <alice@example.com>
 ------------
-- 
2.40.1

Re: [PATCH v4 0/4] doc: interpret-trailers: don't use deprecated config

[Junio C Hamano]

Kristoffer Haugsbakk <code@khaugsbakk.name> writes:

> Replace deprecated `command` with `cmd` (patch 3). While visiting this
> file also:
>
> • rewrite heredoc examples to use files which are shown with
>   cat(1) (patch 1);
> • use input redirection instead of using cat(1) piped into `git
>   interpret-trailers` (patch 2); and
> • fix an example that didn’t work properly (patch 4).
>
> § Changes in v4
>
> • Patch 1: Use `/dev/null` instead of `empty-msg.txt`
> • Patch 2: Expand commit message

Looking good.  Will replace.  I'll ping Christian as the area expert
just in case there is something obvious we missed, but let's aim to
merge this down to 'next' soonish.

Thanks.