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

[Kristoffer Haugsbakk <code@khaugsbakk.name>]

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