{"thread":{"id":"59712","subject":"[PATCH 00/11] docs: interpret-trailers: reword and add examples","startedAt":"2023-05-08T17:27:58Z","lastAt":"2023-06-15T07:48:29Z","messageCount":73,"participants":["Linus Arver via GitGitGadget","Junio C Hamano","Linus Arver","Christian Couder"],"isPatch":true,"patchVersion":1,"patchTotal":11},"messages":[{"id":"476766","messageId":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":null,"subject":"[PATCH 00/11] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:39Z","receivedAt":"2023-05-08T17:27:58Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"This series makes some small improvements to the docs for\ngit-interpret-trailers. The intent is to make it easier to read for\nbeginners who have never used this command before.\n\nLinus Arver (11):\n doc: trailer: fix grammar\n doc: trailer: swap verb order\n doc: trailer: --no-divider: more precise language\n doc: trailer: explain \"commit mesage part\" on first usage\n doc: trailer: remove redundant phrasing\n doc: trailer: trailer..cmd: add missing verb phrase\n doc: trailer: use angle brackets for and \n doc: trailer..command: refer to existing example\n doc: trailer..command: emphasize deprecation\n doc: trailer: mention 'key' in DESCRIPTION\n doc: trailer: add more examples in DESCRIPTION\n\n Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------\n 1 file changed, 40 insertions(+), 22 deletions(-)\n\n\nbase-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v1\nPull-Request: https://github.com/git/git/pull/1506\n-- \ngitgitgadget\n"},{"id":"476767","messageId":"12d4850a9ab8659c40fcb6470caf8f98d7f6e486.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 01/11] doc: trailer: fix grammar","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:40Z","receivedAt":"2023-05-08T17:28:00Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 22ff3a603e0..e695977fbfa 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-- \ngitgitgadget\n\n"},{"id":"476768","messageId":"b771742443723e74459a998fd3b1d0207165b167.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 02/11] doc: trailer: swap verb order","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:41Z","receivedAt":"2023-05-08T17:28:02Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis matches the order already used in the NAME section.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex e695977fbfa..593bc1a1f4e 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-- \ngitgitgadget\n\n"},{"id":"476769","messageId":"ad2d669eb0a6ba1f98af064089ef981c50546958.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 03/11] doc: trailer: --no-divider: more precise language","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:42Z","receivedAt":"2023-05-08T17:28:04Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis uses the phrase \"commit message part\" instead of \"commit message\".\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 593bc1a1f4e..3e60a6eaabc 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -131,7 +131,7 @@ OPTIONS\n \n --no-divider::\n \tDo not treat `---` as the end of the commit message. Use this\n-\twhen you know your input contains just the commit message itself\n+\twhen you know your input contains only the commit message part\n \t(and not an email or the output of `git format-patch`).\n \n CONFIGURATION VARIABLES\n-- \ngitgitgadget\n\n"},{"id":"476770","messageId":"5bad365c78673d3f5b58e4cb3713a9bf718d1fb8.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 05/11] doc: trailer: remove redundant phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:44Z","receivedAt":"2023-05-08T17:28:06Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe phrase \"many rules\" gets essentially repeated again with \"many other\nrules\", so remove this repetition.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 7d6e250f37e..e80a9cd161b 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -68,9 +68,8 @@ inside or after the value. The value may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n-Note that 'trailers' do not follow and are not intended to follow many\n-rules for RFC 822 headers. For example they do not follow\n-the encoding rules and probably many other rules.\n+Note that trailers do not follow (nor are they intended to follow) many of the\n+rules for RFC 822 headers. For example they do not follow the encoding rule.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"476771","messageId":"0c10e40794d208ba408a2b1c394fdbd6caa7a92a.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 04/11] doc: trailer: explain \"commit mesage part\" on first usage","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:43Z","receivedAt":"2023-05-08T17:28:07Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis phrase is used for the first time here, but it's not explained what\nit means. So explain it just in case it's not obvious.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 3e60a6eaabc..7d6e250f37e 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -22,9 +22,9 @@ This command reads some patches or commit messages from either the\n arguments or the standard input if no is specified. If\n `--parse` is specified, the output consists of the parsed trailers.\n \n-Otherwise, this command applies the arguments passed using the\n-`--trailer` option, if any, to the commit message part of each input\n-file. The result is emitted on the standard output.\n+Otherwise, this command applies the arguments passed using the `--trailer`\n+option, if any, to the commit message part of each input file (as opposed to the\n+patch part following a '---' divider). The result is emitted to standard output.\n \n Some configuration variables control the way the `--trailer` arguments\n are applied to each commit message and the way any existing trailer in\n-- \ngitgitgadget\n\n"},{"id":"476772","messageId":"ab11527ca58a7c3f0da657393088919acba78b00.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 07/11] doc: trailer: use angle brackets for and ","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:46Z","receivedAt":"2023-05-08T17:28:09Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nWe already use angle brackets elsewhere, so this makes things more\nconsistent.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex c4675d9d3bb..ac448fd732e 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -62,9 +62,9 @@ space or the end of the line). Such three minus signs start the patch\n part of the message. See also `--no-divider` below.\n \n When reading trailers, there can be no whitespace before or inside the\n-token, but any number of regular space and tab characters are allowed\n-between the token and the separator. There can be whitespaces before,\n-inside or after the value. The value may be split over multiple lines\n+, but any number of regular space and tab characters are allowed\n+between the and the separator. There can be whitespaces before,\n+inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n-- \ngitgitgadget\n\n"},{"id":"476773","messageId":"8e36d1bd1f0c8ca6b1210a537f4bb8403fab7c47.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 06/11] doc: trailer: trailer..cmd: add missing verb phrase","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:45Z","receivedAt":"2023-05-08T17:28:11Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe phrase \"is specified\" is implied. Make it explicit.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex e80a9cd161b..c4675d9d3bb 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -248,10 +248,10 @@ for the same , 'trailer..cmd' is used and\n 'trailer..command' is ignored.\n \n trailer..cmd::\n-\tThis option can be used to specify a shell command that will be called:\n-\tonce to automatically add a trailer with the specified , and then\n-\teach time a '--trailer =' argument to modify the of\n-\tthe trailer that this option would produce.\n+\tThis option can be used to specify a shell command that will be called once\n+\tto automatically add a trailer with the specified , and then called\n+\teach time a '--trailer =' argument is specified to modify the\n+\t of the trailer that this option would produce.\n +\n When the specified command is first called to add a trailer\n with the specified , the behavior is as if a special\n-- \ngitgitgadget\n\n"},{"id":"476774","messageId":"5980432179352054955e602cf97b57e97694a28c.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 08/11] doc: trailer..command: refer to existing example","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:47Z","receivedAt":"2023-05-08T17:28:12Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex ac448fd732e..5ca758e363f 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -234,10 +234,11 @@ trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n-\tThis option behaves in the same way as 'trailer..cmd', except\n-\tthat it doesn't pass anything as argument to the specified command.\n-\tInstead the first occurrence of substring $ARG is replaced by the\n-\tvalue that would be passed as argument.\n+\tThis option behaves in the\n+\tsame way as 'trailer..cmd', except that it doesn't pass anything as\n+\targument to the specified command. Instead the first occurrence of substring\n+\t$ARG is replaced by the from the trailer. See the\n+\t'trailer.see.command' trailer example in the \"EXAMPLES\" section below.\n +\n The 'trailer..command' option has been deprecated in favor of\n 'trailer..cmd' due to the fact that $ARG in the user's command is\n-- \ngitgitgadget\n\n"},{"id":"476775","messageId":"1ac58b0b07c21fe4494f5fbe5d4b0f9bc1a49ac0.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 09/11] doc: trailer..command: emphasize deprecation","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:48Z","receivedAt":"2023-05-08T17:28:17Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis puts the deprecation notice up front, instead of leaving it to the\nnext paragraph.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 5ca758e363f..c9b82ceba34 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -234,7 +234,7 @@ trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n-\tThis option behaves in the\n+\tDeprecated in favor of 'trailer..cmd'. This option behaves in the\n \tsame way as 'trailer..cmd', except that it doesn't pass anything as\n \targument to the specified command. Instead the first occurrence of substring\n \t$ARG is replaced by the from the trailer. See the\n-- \ngitgitgadget\n\n"},{"id":"476776","messageId":"2c04a5ba7f0ac16fe648c7dac2684523429378af.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 10/11] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:49Z","receivedAt":"2023-05-08T17:28:25Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe 'key' option is used frequently in the examples at the bottom but\nthere is no mention of it in the description.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex c9b82ceba34..119dcd64f34 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -43,7 +43,9 @@ token: value\n ------------------------------------------------\n \n This means that the trimmed and will be separated by\n-`': '` (one colon followed by one space).\n+`': '` (one colon followed by one space). If the should have a different\n+string representation than itself, then the 'key' can be configured with\n+'trailer..key'.\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-- \ngitgitgadget\n\n"},{"id":"476777","messageId":"ea483b364b460819c727da5c65497de6ecd4b04f.1683566870.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH 11/11] doc: trailer: add more examples in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-08T17:27:50Z","receivedAt":"2023-05-08T17:28:27Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nBe more up-front about what trailers are in practice with examples, to\ngive the reader a visual cue while they go on to read the rest of the\ndescription.\n\nAlso add an example for multiline values.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--\n 1 file changed, 18 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 119dcd64f34..f31b94a6823 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -16,7 +16,18 @@ DESCRIPTION\n -----------\n Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n-message.\n+message. For example, in the following commit message\n+\n+------------------------------------------------\n+subject\n+\n+message\n+\n+Signed-off-by: Alice \n+Signed-off-by: Bob \n+------------------------------------------------\n+\n+the last two lines starting with \"Signed-off-by\" are trailers.\n \n This command reads some patches or commit messages from either the\n arguments or the standard input if no is specified. If\n@@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the\n between the and the separator. There can be whitespaces before,\n inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n-the \"folding\" in RFC 822.\n+the \"folding\" in RFC 822. Example:\n+\n+------------------------------------------------\n+token: Lorem ipsum dolor sit amet, consectetur\n+ adipiscing elit.\n+------------------------------------------------\n \n Note that trailers do not follow (nor are they intended to follow) many of the\n rules for RFC 822 headers. For example they do not follow the encoding rule.\n-- \ngitgitgadget\n"},{"id":"476782","messageId":"xmqqy1lypvb4.fsf@gitster.g","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"Re: [PATCH 00/11] docs: interpret-trailers: reword and add examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T17:49:51Z","receivedAt":"2023-05-08T17:49:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"[jc: making sure that the area expert is aware of the topic]\n\n\"Linus Arver via GitGitGadget\" writes:\n\n> This series makes some small improvements to the docs for\n> git-interpret-trailers. The intent is to make it easier to read for\n> beginners who have never used this command before.\n>\n> Linus Arver (11):\n> doc: trailer: fix grammar\n> doc: trailer: swap verb order\n> doc: trailer: --no-divider: more precise language\n> doc: trailer: explain \"commit mesage part\" on first usage\n> doc: trailer: remove redundant phrasing\n> doc: trailer: trailer..cmd: add missing verb phrase\n> doc: trailer: use angle brackets for and \n> doc: trailer..command: refer to existing example\n> doc: trailer..command: emphasize deprecation\n> doc: trailer: mention 'key' in DESCRIPTION\n> doc: trailer: add more examples in DESCRIPTION\n>\n> Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------\n> 1 file changed, 40 insertions(+), 22 deletions(-)\n>\n>\n> base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v1\n> Pull-Request: https://github.com/git/git/pull/1506\n"},{"id":"476793","messageId":"owlysfc6myl8.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqy1lypvb4.fsf@gitster.g","subject":"Re: [PATCH 00/11] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-08T19:07:15Z","receivedAt":"2023-05-08T19:07:20Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> [jc: making sure that the area expert is aware of the topic]\n\nThanks for the assist, Junio! (I will run git-blame next time, sorry\nabout that.)\n\nBut also, what does the `jc: ` in your message stand for?\n\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> This series makes some small improvements to the docs for\n>> git-interpret-trailers. The intent is to make it easier to read for\n>> beginners who have never used this command before.\n\n>> Linus Arver (11):\n>> doc: trailer: fix grammar\n>> doc: trailer: swap verb order\n>> doc: trailer: --no-divider: more precise language\n>> doc: trailer: explain \"commit mesage part\" on first usage\n>> doc: trailer: remove redundant phrasing\n>> doc: trailer: trailer..cmd: add missing verb phrase\n>> doc: trailer: use angle brackets for and \n>> doc: trailer..command: refer to existing example\n>> doc: trailer..command: emphasize deprecation\n>> doc: trailer: mention 'key' in DESCRIPTION\n>> doc: trailer: add more examples in DESCRIPTION\n\n>> Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------\n>> 1 file changed, 40 insertions(+), 22 deletions(-)\n\n\n>> base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8\n>> Published-As: \n>> https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1\n>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git \n>> pr-git-1506/listx/doc-trailer-v1\n>> Pull-Request: https://github.com/git/git/pull/1506\n"},{"id":"476794","messageId":"xmqqpm7aoclp.fsf@gitster.g","threadId":"59712","inReplyTo":"12d4850a9ab8659c40fcb6470caf8f98d7f6e486.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 01/11] doc: trailer: fix grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:19:14Z","receivedAt":"2023-05-08T19:19:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index 22ff3a603e0..e695977fbfa 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -14,7 +14,7 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n> +Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n> headers, at the end of the otherwise free-form part of a commit\n> message.\n\nIs that a grammatically incorrect sentence?\n\nThe command does help doing these two things, but we can say the\ncommand does these two things without closing clarity, so I do not\nhave an objection to the updated text (the only \"ungrammatical\" part\nmay be that \", that look\" should probably be \"that look\"), but I am\nnot sure if \"fix grammar\" is a good explanation for this commit.\n"},{"id":"476797","messageId":"xmqqlehyocjr.fsf@gitster.g","threadId":"59712","inReplyTo":"b771742443723e74459a998fd3b1d0207165b167.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 02/11] doc: trailer: swap verb order","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:20:24Z","receivedAt":"2023-05-08T19:20:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> This matches the order already used in the NAME section.\n\nThe change makes sense, and the explanation above is also clear.\n\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index e695977fbfa..593bc1a1f4e 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -14,7 +14,7 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> -Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n> +Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n> headers, at the end of the otherwise free-form part of a commit\n> message.\n"},{"id":"476798","messageId":"xmqqednqoc04.fsf@gitster.g","threadId":"59712","inReplyTo":"ad2d669eb0a6ba1f98af064089ef981c50546958.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 03/11] doc: trailer: --no-divider: more precise language","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:32:11Z","receivedAt":"2023-05-08T19:32:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> This uses the phrase \"commit message part\" instead of \"commit message\".\n\nThat much anybody can see from the patch. The question is, is the\nupdated phrasing \"more precise\"?\n\nTo me (a non native English speaker), both the original and the\nupdated text say mostly the same thing, but the added word \"part\"\nactually made my reading hiccup a bit.\n\nIt may be because for the word \"part\" to sit well, it is not clear\nenough what \"your input\" consists of in the updated text. If it\nwere somehow clear to readers that \"your input\" consists of \"commit\nmessage part\", \"some other message part\", and \"yet another message\npart\", divided with a three-dash lines, then \"commit message part\"\nmight become a good phrasing. An email can have any garbage in it,\na format-patfch output has commit message and patch text. So \"only\nthe commit message\" or \"just the commit message\" without \"itself\"\nmay be an improvement in clarity, in the same sense that 01/11 made\na sentence say the same sense with a fewer words, but personally I\ndo not find the posted patch as-is that much of an improvement.\n\nI dunno.\n\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index 593bc1a1f4e..3e60a6eaabc 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -131,7 +131,7 @@ OPTIONS\n> \n> --no-divider::\n> \tDo not treat `---` as the end of the commit message. Use this\n> -\twhen you know your input contains just the commit message itself\n> +\twhen you know your input contains only the commit message part\n> \t(and not an email or the output of `git format-patch`).\n> \n> CONFIGURATION VARIABLES\n"},{"id":"476799","messageId":"owlypm7amxdn.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqpm7aoclp.fsf@gitster.g","subject":"Re: [PATCH 01/11] doc: trailer: fix grammar","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-08T19:33:24Z","receivedAt":"2023-05-08T19:33:31Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> From: Linus Arver \n\n>> Signed-off-by: Linus Arver \n>> ---\n>> Documentation/git-interpret-trailers.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n\n>> diff --git a/Documentation/git-interpret-trailers.txt \n>> b/Documentation/git-interpret-trailers.txt\n>> index 22ff3a603e0..e695977fbfa 100644\n>> --- a/Documentation/git-interpret-trailers.txt\n>> +++ b/Documentation/git-interpret-trailers.txt\n>> @@ -14,7 +14,7 @@ SYNOPSIS\n\n>> DESCRIPTION\n>> -----------\n>> -Help parsing or adding 'trailers' lines, that look similar to RFC 822 \n>> e-mail\n>> +Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n>> headers, at the end of the otherwise free-form part of a commit\n>> message.\n\n> Is that a grammatically incorrect sentence?\n\nI think so. If we remove the dependent clauses starting with \"that look\nsimilar ...\", we just get\n\n Help parsing or adding 'trailers' lines\n\nwhich cannot stand on its own as an independent clause. The correct\nversion would be\n\n Help parse or add 'trailers' lines\n\nwhich is what I first considered. However the auxiliary verb \"help\" here\ndoesn't really mean much, because the interpret-trailers builtin already\nis _the_ authority for parsing or adding trailer lines, so I opted to\nremove it in my patch.\n\n> The command does help doing these two things, but we can say the\n> command does these two things without closing clarity, so I do not\n> have an objection to the updated text\n\nExactly (I think you meant s/closing/losing here).\n\n> (the only \"ungrammatical\" part\n> may be that \", that look\" should probably be \"that look\"), but I am\n> not sure if \"fix grammar\" is a good explanation for this commit.\n\nI think punctuation (especially with commas) can be pretty wide-ranging\nin terms of what is acceptable or not in terms of grammar. But looking\nat it again I like your version with the comma removed. I'll make the\nchange locally for a v2 series.\n"},{"id":"476800","messageId":"xmqqa5yeobrj.fsf@gitster.g","threadId":"59712","inReplyTo":"0c10e40794d208ba408a2b1c394fdbd6caa7a92a.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 04/11] doc: trailer: explain \"commit mesage part\" on first usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:37:20Z","receivedAt":"2023-05-08T19:37:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> This phrase is used for the first time here, but it's not explained what\n> it means. So explain it just in case it's not obvious.\n\n03+04 should be a single patch (as I read more, I may find other\nsteps should also be in a single step, I dunno); otherwise it would\nwaste reviewer's time (just like I did thinking and writing about\n03/11).\n\nOr just drop \"part\". \"git cat-file commit HEAD | sed -e '1,/^$/d'\"\nis a good material to use with \"--no-divider\" because it only has\nthe \"commit message\". The \"part\" implies you first had something\nthat has both \"commit message\" and something else and you split\nthat combination into two (or more) parts. But that does not have\nto be the case. I think that made 03/11 confusing, at least to me.\n\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index 3e60a6eaabc..7d6e250f37e 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -22,9 +22,9 @@ This command reads some patches or commit messages from either the\n> arguments or the standard input if no is specified. If\n> `--parse` is specified, the output consists of the parsed trailers.\n> \n> -Otherwise, this command applies the arguments passed using the\n> -`--trailer` option, if any, to the commit message part of each input\n> -file. The result is emitted on the standard output.\n> +Otherwise, this command applies the arguments passed using the `--trailer`\n> +option, if any, to the commit message part of each input file (as opposed to the\n> +patch part following a '---' divider). The result is emitted to standard output.\n> \n> Some configuration variables control the way the `--trailer` arguments\n> are applied to each commit message and the way any existing trailer in\n"},{"id":"476801","messageId":"xmqq5y92obq2.fsf@gitster.g","threadId":"59712","inReplyTo":"ab11527ca58a7c3f0da657393088919acba78b00.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 07/11] doc: trailer: use angle brackets for and ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:38:13Z","receivedAt":"2023-05-08T19:38:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> We already use angle brackets elsewhere, so this makes things more\n> consistent.\n\nExcellent.\n\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index c4675d9d3bb..ac448fd732e 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -62,9 +62,9 @@ space or the end of the line). Such three minus signs start the patch\n> part of the message. See also `--no-divider` below.\n> \n> When reading trailers, there can be no whitespace before or inside the\n> -token, but any number of regular space and tab characters are allowed\n> -between the token and the separator. There can be whitespaces before,\n> -inside or after the value. The value may be split over multiple lines\n> +, but any number of regular space and tab characters are allowed\n> +between the and the separator. There can be whitespaces before,\n> +inside or after the . The may be split over multiple lines\n> with each subsequent line starting with at least one whitespace, like\n> the \"folding\" in RFC 822.\n"},{"id":"476802","messageId":"xmqq1qjqobl9.fsf@gitster.g","threadId":"59712","inReplyTo":"8e36d1bd1f0c8ca6b1210a537f4bb8403fab7c47.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 06/11] doc: trailer: trailer..cmd: add missing verb phrase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:41:06Z","receivedAt":"2023-05-08T19:41:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> The phrase \"is specified\" is implied. Make it explicit.\n\nMakes sense. Calling it \"implied\" is generous ;-) Isn't the\noriginal just outright ungrammatical?\n\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 8 ++++----\n> 1 file changed, 4 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index e80a9cd161b..c4675d9d3bb 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -248,10 +248,10 @@ for the same , 'trailer..cmd' is used and\n> 'trailer..command' is ignored.\n> \n> trailer..cmd::\n> -\tThis option can be used to specify a shell command that will be called:\n> -\tonce to automatically add a trailer with the specified , and then\n> -\teach time a '--trailer =' argument to modify the of\n> -\tthe trailer that this option would produce.\n> +\tThis option can be used to specify a shell command that will be called once\n> +\tto automatically add a trailer with the specified , and then called\n> +\teach time a '--trailer =' argument is specified to modify the\n> +\t of the trailer that this option would produce.\n> +\n> When the specified command is first called to add a trailer\n> with the specified , the behavior is as if a special\n"},{"id":"476803","messageId":"xmqqwn1imwqk.fsf@gitster.g","threadId":"59712","inReplyTo":"5980432179352054955e602cf97b57e97694a28c.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 08/11] doc: trailer..command: refer to existing example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:47:15Z","receivedAt":"2023-05-08T19:50:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 9 +++++----\n> 1 file changed, 5 insertions(+), 4 deletions(-)\n\nThis patch has more annoying \"just rewrapping the text in a strange\nway without changing anything\" than the real change which is to\nenclose inside the angle brackets (which is good) and adding\na new sentence.\n\nWe are discouraging the use of .command and recommending folks to\nuse .cmd instead, by the way. At some point we may drop the\nexample, and adding a reference to the example would mean somebody\nneeds to remember removing this when it happens.\n\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index ac448fd732e..5ca758e363f 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -234,10 +234,11 @@ trailer..ifmissing::\n> \tthat option for trailers with the specified .\n> \n> trailer..command::\n> -\tThis option behaves in the same way as 'trailer..cmd', except\n> -\tthat it doesn't pass anything as argument to the specified command.\n> -\tInstead the first occurrence of substring $ARG is replaced by the\n> -\tvalue that would be passed as argument.\n> +\tThis option behaves in the\n> +\tsame way as 'trailer..cmd', except that it doesn't pass anything as\n> +\targument to the specified command. Instead the first occurrence of substring\n> +\t$ARG is replaced by the from the trailer. See the\n> +\t'trailer.see.command' trailer example in the \"EXAMPLES\" section below.\n> +\n> The 'trailer..command' option has been deprecated in favor of\n> 'trailer..cmd' due to the fact that $ARG in the user's command is\n"},{"id":"476804","messageId":"xmqqsfc6mwok.fsf@gitster.g","threadId":"59712","inReplyTo":"1ac58b0b07c21fe4494f5fbe5d4b0f9bc1a49ac0.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 09/11] doc: trailer..command: emphasize deprecation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:48:27Z","receivedAt":"2023-05-08T19:50:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> This puts the deprecation notice up front, instead of leaving it to the\n> next paragraph.\n\nShouldn't the opening text of the next paragraph be tweaked in the\nsame commit to avoid duplication?\n\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index 5ca758e363f..c9b82ceba34 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -234,7 +234,7 @@ trailer..ifmissing::\n> \tthat option for trailers with the specified .\n> \n> trailer..command::\n> -\tThis option behaves in the\n> +\tDeprecated in favor of 'trailer..cmd'. This option behaves in the\n> \tsame way as 'trailer..cmd', except that it doesn't pass anything as\n> \targument to the specified command. Instead the first occurrence of substring\n> \t$ARG is replaced by the from the trailer. See the\n"},{"id":"476805","messageId":"xmqqmt2emwlj.fsf@gitster.g","threadId":"59712","inReplyTo":"ea483b364b460819c727da5c65497de6ecd4b04f.1683566870.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 11/11] doc: trailer: add more examples in DESCRIPTION","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T19:50:16Z","receivedAt":"2023-05-08T19:52:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> From: Linus Arver \n>\n> Be more up-front about what trailers are in practice with examples, to\n> give the reader a visual cue while they go on to read the rest of the\n> description.\n>\n> Also add an example for multiline values.\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--\n> 1 file changed, 18 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index 119dcd64f34..f31b94a6823 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -16,7 +16,18 @@ DESCRIPTION\n> -----------\n> Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n> headers, at the end of the otherwise free-form part of a commit\n> -message.\n> +message. For example, in the following commit message\n> +\n> +------------------------------------------------\n> +subject\n> +\n> +message\n> +\n> +Signed-off-by: Alice \n> +Signed-off-by: Bob \n> +------------------------------------------------\n> +\n> +the last two lines starting with \"Signed-off-by\" are trailers.\n\nExcellent.\n\n> @@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the\n> between the and the separator. There can be whitespaces before,\n> inside or after the . The may be split over multiple lines\n> with each subsequent line starting with at least one whitespace, like\n> -the \"folding\" in RFC 822.\n> +the \"folding\" in RFC 822. Example:\n> +\n> +------------------------------------------------\n> +token: Lorem ipsum dolor sit amet, consectetur\n> + adipiscing elit.\n> +------------------------------------------------\n\nExcellent.\n\n"},{"id":"476815","messageId":"xmqqa5yemrqq.fsf@gitster.g","threadId":"59712","inReplyTo":"owlypm7amxdn.fsf@fine.c.googlers.com","subject":"Re: [PATCH 01/11] doc: trailer: fix grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-08T21:35:09Z","receivedAt":"2023-05-08T21:35:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n> which cannot stand on its own as an independent clause. The correct\n> version would be\n>\n> Help parse or add 'trailers' lines\n\nYou're indeed correct. Thanks.\n"},{"id":"476946","messageId":"owlymt2cn0rm.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqa5yeobrj.fsf@gitster.g","subject":"Re: [PATCH 04/11] doc: trailer: explain \"commit mesage part\" on first usage","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-10T06:44:45Z","receivedAt":"2023-05-10T06:45:06Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> From: Linus Arver \n\n>> This phrase is used for the first time here, but it's not explained what\n>> it means. So explain it just in case it's not obvious.\n\n> 03+04 should be a single patch\n\nAgreed.\n\n> otherwise it would\n> waste reviewer's time (just like I did thinking and writing about\n> 03/11).\n\nThank you for the pointer. I will be more careful about patch order\nmoving forward.\n\n> Or just drop \"part\". \"git cat-file commit HEAD | sed -e '1,/^$/d'\"\n> is a good material to use with \"--no-divider\" because it only has\n> the \"commit message\". The \"part\" implies you first had something\n> that has both \"commit message\" and something else and you split\n> that combination into two (or more) parts. But that does not have\n> to be the case. I think that made 03/11 confusing, at least to me.\n\nLooking back, I don't think I had a good grasp of what \"commit message\npart\" meant. When I wrote this series I thought \"commit message part\"\nmeant everything in the output of git-format-patch until hitting the\n\"---\" divider. But as you point out in your\n\n git cat-file commit HEAD | sed -e '1,/^$/d'\n\nexample, technically there is never any ambiguity of what the commit\nmessage contains (it only contains a commit message, not a \"commit\nmessage part\" and a separate \"patch part\"). And the output of\ngit-format-patch is a patch (which contains the commit message and also\nother things), not a commit message with different subparts. I was\noperating under this flawed understanding, oops.\n\nThat being said, there are several instances in the DESCRIPTION section\nwhen we use the \"commit message part\" phrasing (as opposed to just\n\"commit message\"). I am leaning toward just dropping \"part\" as you\nsuggested. Also, I think we should add an explanation of how\ngit-interpret-trailers sees the incoming text, how it gives special\ntreatment to a \"---\" divider line, how it uses this line to mark off a\ncommit message part (and then uses this part as the default location of\nadding trailers, unless specifying a \"--no-divider\" flag), etc. This\ncould be in a revamped 03+04 patch, or perhaps left out until another\nday. I'll see what I can do in v2.\n\n>> Signed-off-by: Linus Arver \n>> ---\n>> Documentation/git-interpret-trailers.txt | 6 +++---\n>> 1 file changed, 3 insertions(+), 3 deletions(-)\n\n>> diff --git a/Documentation/git-interpret-trailers.txt \n>> b/Documentation/git-interpret-trailers.txt\n>> index 3e60a6eaabc..7d6e250f37e 100644\n>> --- a/Documentation/git-interpret-trailers.txt\n>> +++ b/Documentation/git-interpret-trailers.txt\n>> @@ -22,9 +22,9 @@ This command reads some patches or commit messages \n>> from either the\n>> arguments or the standard input if no is specified. If\n>> `--parse` is specified, the output consists of the parsed trailers.\n\n>> -Otherwise, this command applies the arguments passed using the\n>> -`--trailer` option, if any, to the commit message part of each input\n>> -file. The result is emitted on the standard output.\n>> +Otherwise, this command applies the arguments passed using the \n>> `--trailer`\n>> +option, if any, to the commit message part of each input file (as \n>> opposed to the\n>> +patch part following a '---' divider). The result is emitted to \n>> standard output.\n\n>> Some configuration variables control the way the `--trailer` arguments\n>> are applied to each commit message and the way any existing trailer in\n"},{"id":"476947","messageId":"owlyjzxgn0et.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqq1qjqobl9.fsf@gitster.g","subject":"Re: [PATCH 06/11] doc: trailer: trailer..cmd: add missing verb phrase","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-10T06:52:26Z","receivedAt":"2023-05-10T06:52:31Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> From: Linus Arver \n\n>> The phrase \"is specified\" is implied. Make it explicit.\n\n> Makes sense. Calling it \"implied\" is generous ;-)\n\nHaha yes, I suppose so. I wrote \"implied\" because supplying the\n(missing) phrase \"is specified\" was the only way I could make sense of\nthe existing wording.\n\n> Isn't the\n> original just outright ungrammatical?\n\nIndeed.\n\nShould I combine 01+06 together?\n\n\n\n>> Signed-off-by: Linus Arver \n>> ---\n>> Documentation/git-interpret-trailers.txt | 8 ++++----\n>> 1 file changed, 4 insertions(+), 4 deletions(-)\n\n>> diff --git a/Documentation/git-interpret-trailers.txt \n>> b/Documentation/git-interpret-trailers.txt\n>> index e80a9cd161b..c4675d9d3bb 100644\n>> --- a/Documentation/git-interpret-trailers.txt\n>> +++ b/Documentation/git-interpret-trailers.txt\n>> @@ -248,10 +248,10 @@ for the same , 'trailer..cmd' is \n>> used and\n>> 'trailer..command' is ignored.\n\n>> trailer..cmd::\n>> -\tThis option can be used to specify a shell command that will be called:\n>> -\tonce to automatically add a trailer with the specified , and \n>> then\n>> -\teach time a '--trailer =' argument to modify the \n>> of\n>> -\tthe trailer that this option would produce.\n>> +\tThis option can be used to specify a shell command that will be called \n>> once\n>> +\tto automatically add a trailer with the specified , and then \n>> called\n>> +\teach time a '--trailer =' argument is specified to \n>> modify the\n>> +\t of the trailer that this option would produce.\n>> +\n>> When the specified command is first called to add a trailer\n>> with the specified , the behavior is as if a special\n"},{"id":"476948","messageId":"owlyh6skmznt.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqwn1imwqk.fsf@gitster.g","subject":"Re: [PATCH 08/11] doc: trailer..command: refer to existing example","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-10T07:08:38Z","receivedAt":"2023-05-10T07:08:48Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> From: Linus Arver \n\n>> Signed-off-by: Linus Arver \n>> ---\n>> Documentation/git-interpret-trailers.txt | 9 +++++----\n>> 1 file changed, 5 insertions(+), 4 deletions(-)\n\n> This patch has more annoying \"just rewrapping the text in a strange\n> way without changing anything\"\n\nNoted. I will remove the whitespace churn in v2.\n\n> than the real change which is to\n> enclose inside the angle brackets (which is good) and adding\n> a new sentence.\n\nI should probably move the angle bracket changes into 07.\n\n> We are discouraging the use of .command and recommending folks to\n> use .cmd instead, by the way.\n\nI was motivated to add the reference to the example because I could not\nunderstand what\n\n Instead the first occurrence of substring $ARG is replaced by the\n value that would be passed as argument.\n\nmeant in the existing language. In hindsight maybe it's not worth adding\nthe reference, because of the deprecation.\n\n> At some point we may drop the\n> example, and adding a reference to the example would mean somebody\n> needs to remember removing this when it happens.\n\nWouldn't we also delete the entire `trailer..command::` section\n(and therefore the reference to the example) also at the same time?\n\n>> diff --git a/Documentation/git-interpret-trailers.txt \n>> b/Documentation/git-interpret-trailers.txt\n>> index ac448fd732e..5ca758e363f 100644\n>> --- a/Documentation/git-interpret-trailers.txt\n>> +++ b/Documentation/git-interpret-trailers.txt\n>> @@ -234,10 +234,11 @@ trailer..ifmissing::\n>> \tthat option for trailers with the specified .\n\n>> trailer..command::\n>> -\tThis option behaves in the same way as 'trailer..cmd', except\n>> -\tthat it doesn't pass anything as argument to the specified command.\n>> -\tInstead the first occurrence of substring $ARG is replaced by the\n>> -\tvalue that would be passed as argument.\n>> +\tThis option behaves in the\n>> +\tsame way as 'trailer..cmd', except that it doesn't pass \n>> anything as\n>> +\targument to the specified command. Instead the first occurrence of \n>> substring\n>> +\t$ARG is replaced by the from the trailer. See the\n>> +\t'trailer.see.command' trailer example in the \"EXAMPLES\" section below.\n>> +\n>> The 'trailer..command' option has been deprecated in favor of\n>> 'trailer..cmd' due to the fact that $ARG in the user's command is\n"},{"id":"476949","messageId":"owlyednomzkc.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqsfc6mwok.fsf@gitster.g","subject":"Re: [PATCH 09/11] doc: trailer..command: emphasize deprecation","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-10T07:10:43Z","receivedAt":"2023-05-10T07:10:50Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Junio C Hamano writes:\n\n> \"Linus Arver via GitGitGadget\" writes:\n\n>> From: Linus Arver \n\n>> This puts the deprecation notice up front, instead of leaving it to the\n>> next paragraph.\n\n> Shouldn't the opening text of the next paragraph be tweaked in the\n> same commit to avoid duplication?\n\nGood call; will do in v2.\n\n\n>> Signed-off-by: Linus Arver \n>> ---\n>> Documentation/git-interpret-trailers.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n\n>> diff --git a/Documentation/git-interpret-trailers.txt \n>> b/Documentation/git-interpret-trailers.txt\n>> index 5ca758e363f..c9b82ceba34 100644\n>> --- a/Documentation/git-interpret-trailers.txt\n>> +++ b/Documentation/git-interpret-trailers.txt\n>> @@ -234,7 +234,7 @@ trailer..ifmissing::\n>> \tthat option for trailers with the specified .\n\n>> trailer..command::\n>> -\tThis option behaves in the\n>> +\tDeprecated in favor of 'trailer..cmd'. This option behaves in \n>> the\n>> \tsame way as 'trailer..cmd', except that it doesn't pass \n>> anything as\n>> \targument to the specified command. Instead the first occurrence of \n>> substring\n>> \t$ARG is replaced by the from the trailer. See the\n"},{"id":"476978","messageId":"xmqqlehw5eiu.fsf@gitster.g","threadId":"59712","inReplyTo":"owlyjzxgn0et.fsf@fine.c.googlers.com","subject":"Re: [PATCH 06/11] doc: trailer: trailer..cmd: add missing verb phrase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-10T16:37:13Z","receivedAt":"2023-05-10T16:37:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n>> Isn't the\n>> original just outright ungrammatical?\n>\n> Indeed.\n>\n> Should I combine 01+06 together?\n\nEither is fine. Thanks.\n"},{"id":"476979","messageId":"xmqqfs845e98.fsf@gitster.g","threadId":"59712","inReplyTo":"owlyh6skmznt.fsf@fine.c.googlers.com","subject":"Re: [PATCH 08/11] doc: trailer..command: refer to existing example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-10T16:42:59Z","receivedAt":"2023-05-10T16:43:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n>> At some point we may drop the\n>> example, and adding a reference to the example would mean somebody\n>> needs to remember removing this when it happens.\n>\n> Wouldn't we also delete the entire `trailer..command::` section\n> (and therefore the reference to the example) also at the same time?\n\nWe could go that way.\n\nIt is likely that we'd remove text that helps for those who newly\nuse the deprecated construct while keeping what helps for those who\nhave to read and understand the construct that was written in random\nscripts they find on the Internet. So removing the example can come\nbefore the section itself, though.\n\nIn a far enough future, we would be without the example and the\nsection so it would not be too big a deal, either way.\n\nThanks.\n"},{"id":"477088","messageId":"65e6fbdec9248f24fbc0b40ce15c628f0167d901.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 1/9] doc: trailer: fix grammar","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:27Z","receivedAt":"2023-05-11T21:19:43Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 22ff3a603e0..1a1d6288b17 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n+Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n@@ -249,10 +249,10 @@ for the same , 'trailer..cmd' is used and\n 'trailer..command' is ignored.\n \n trailer..cmd::\n-\tThis option can be used to specify a shell command that will be called:\n+\tThis option can be used to specify a shell command that will be called\n \tonce to automatically add a trailer with the specified , and then\n-\teach time a '--trailer =' argument to modify the of\n-\tthe trailer that this option would produce.\n+\tcalled each time a '--trailer =' argument is specified to\n+\tmodify the of the trailer that this option would produce.\n +\n When the specified command is first called to add a trailer\n with the specified , the behavior is as if a special\n-- \ngitgitgadget\n\n"},{"id":"477089","messageId":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.git.git.1683566870.gitgitgadget@gmail.com","subject":"[PATCH v2 0/9] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:26Z","receivedAt":"2023-05-11T21:19:46Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"This series makes some small improvements to the docs for\ngit-interpret-trailers. The intent is to make it easier to read for\nbeginners who have never used this command before.\n\n\nChanges from v1\n===============\n\nIn order of significance:\n\n * The phrase \"commit message part\" has been removed.\n * The word \"message\" is always used as part of the bigger phrase \"commit\n message\".\n * Deprecation language for trailer..command has been updated to\n minimize whitespace churn, while also tweaking the 2nd paragraph to\n reduce duplication.\n * The phrase \"Lorem ipsum...\" is always only used to stand in for the body\n paragraph(s) of a commit message.\n * Grammar fixes have been squashed together (01+06 previously).\n\nLinus Arver (9):\n doc: trailer: fix grammar\n doc: trailer: swap verb order\n doc: trailer: drop \"commit message part\" phrasing\n doc: trailer: examples: avoid the word \"message\" by itself\n doc: trailer: remove redundant phrasing\n doc: trailer: use angle brackets for and \n doc: trailer..command: emphasize deprecation\n doc: trailer: mention 'key' in DESCRIPTION\n doc: trailer: add more examples in DESCRIPTION\n\n Documentation/git-interpret-trailers.txt | 124 +++++++++++++----------\n 1 file changed, 72 insertions(+), 52 deletions(-)\n\n\nbase-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v2\nPull-Request: https://github.com/git/git/pull/1506\n\nRange-diff vs v1:\n\n 1: 12d4850a9ab ! 1: 65e6fbdec92 doc: trailer: fix grammar\n @@ Documentation/git-interpret-trailers.txt: SYNOPSIS\n DESCRIPTION\n -----------\n -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n -+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n ++Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n +@@ Documentation/git-interpret-trailers.txt: for the same , 'trailer..cmd' is used and\n + 'trailer..command' is ignored.\n + \n + trailer..cmd::\n +-\tThis option can be used to specify a shell command that will be called:\n ++\tThis option can be used to specify a shell command that will be called\n + \tonce to automatically add a trailer with the specified , and then\n +-\teach time a '--trailer =' argument to modify the of\n +-\tthe trailer that this option would produce.\n ++\tcalled each time a '--trailer =' argument is specified to\n ++\tmodify the of the trailer that this option would produce.\n + +\n + When the specified command is first called to add a trailer\n + with the specified , the behavior is as if a special\n 2: b7717424437 ! 2: 82353471831 doc: trailer: swap verb order\n @@ Documentation/git-interpret-trailers.txt: SYNOPSIS\n \n DESCRIPTION\n -----------\n --Parse or add 'trailer' lines, that look similar to RFC 822 e-mail\n -+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n +-Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n ++Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n 3: ad2d669eb0a < -: ----------- doc: trailer: --no-divider: more precise language\n 4: 0c10e40794d < -: ----------- doc: trailer: explain \"commit mesage part\" on first usage\n -: ----------- > 3: 5fabe166714 doc: trailer: drop \"commit message part\" phrasing\n -: ----------- > 4: 783a0b1e003 doc: trailer: examples: avoid the word \"message\" by itself\n 5: 5bad365c786 = 5: dd7e29fcc21 doc: trailer: remove redundant phrasing\n 6: 8e36d1bd1f0 < -: ----------- doc: trailer: trailer..cmd: add missing verb phrase\n 7: ab11527ca58 ! 6: 96cb4ae2965 doc: trailer: use angle brackets for and \n @@ Commit message\n Signed-off-by: Linus Arver \n \n ## Documentation/git-interpret-trailers.txt ##\n -@@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such three minus signs start the patch\n - part of the message. See also `--no-divider` below.\n +@@ Documentation/git-interpret-trailers.txt: non-whitespace lines before a line that starts with '---' (followed by a\n + space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n -token, but any number of regular space and tab characters are allowed\n @@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such th\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n +@@ Documentation/git-interpret-trailers.txt: trailer..command::\n + \tThis option behaves in the same way as 'trailer..cmd', except\n + \tthat it doesn't pass anything as argument to the specified command.\n + \tInstead the first occurrence of substring $ARG is replaced by the\n +-\tvalue that would be passed as argument.\n ++\t that would be passed as argument.\n + +\n + The 'trailer..command' option has been deprecated in favor of\n + 'trailer..cmd' due to the fact that $ARG in the user's command is\n 8: 59804321793 ! 7: 4e234110ffd doc: trailer..command: refer to existing example\n @@ Metadata\n Author: Linus Arver \n \n ## Commit message ##\n - doc: trailer..command: refer to existing example\n + doc: trailer..command: emphasize deprecation\n +\n + This puts the deprecation notice up front, instead of leaving it to the\n + next paragraph.\n \n Signed-off-by: Linus Arver \n \n @@ Documentation/git-interpret-trailers.txt: trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n --\tThis option behaves in the same way as 'trailer..cmd', except\n --\tthat it doesn't pass anything as argument to the specified command.\n --\tInstead the first occurrence of substring $ARG is replaced by the\n --\tvalue that would be passed as argument.\n -+\tThis option behaves in the\n -+\tsame way as 'trailer..cmd', except that it doesn't pass anything as\n -+\targument to the specified command. Instead the first occurrence of substring\n -+\t$ARG is replaced by the from the trailer. See the\n -+\t'trailer.see.command' trailer example in the \"EXAMPLES\" section below.\n ++\tDeprecated in favor of 'trailer..cmd'.\n + \tThis option behaves in the same way as 'trailer..cmd', except\n + \tthat it doesn't pass anything as argument to the specified command.\n + \tInstead the first occurrence of substring $ARG is replaced by the\n + \t that would be passed as argument.\n + +\n +-The 'trailer..command' option has been deprecated in favor of\n +-'trailer..cmd' due to the fact that $ARG in the user's command is\n ++Note that $ARG in the user's command is\n + only replaced once and that the original way of replacing $ARG is not safe.\n +\n - The 'trailer..command' option has been deprecated in favor of\n - 'trailer..cmd' due to the fact that $ARG in the user's command is\n + When both 'trailer..cmd' and 'trailer..command' are given\n 9: 1ac58b0b07c < -: ----------- doc: trailer..command: emphasize deprecation\n 10: 2c04a5ba7f0 = 8: 8aaf9e27d98 doc: trailer: mention 'key' in DESCRIPTION\n 11: ea483b364b4 ! 9: 7e95198894b doc: trailer: add more examples in DESCRIPTION\n @@ Commit message\n ## Documentation/git-interpret-trailers.txt ##\n @@ Documentation/git-interpret-trailers.txt: DESCRIPTION\n -----------\n - Add or parse 'trailer' lines, that look similar to RFC 822 e-mail\n + Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n -message.\n +message. For example, in the following commit message\n @@ Documentation/git-interpret-trailers.txt: DESCRIPTION\n +------------------------------------------------\n +subject\n +\n -+message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n +\n +Signed-off-by: Alice \n +Signed-off-by: Bob \n @@ Documentation/git-interpret-trailers.txt: DESCRIPTION\n +\n +the last two lines starting with \"Signed-off-by\" are trailers.\n \n - This command reads some patches or commit messages from either the\n - arguments or the standard input if no is specified. If\n + This command reads commit messages from either the\n + arguments or the standard input if no is specified.\n @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no whitespace before or inside the\n between the and the separator. There can be whitespaces before,\n inside or after the . The may be split over multiple lines\n @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no\n +the \"folding\" in RFC 822. Example:\n +\n +------------------------------------------------\n -+token: Lorem ipsum dolor sit amet, consectetur\n -+ adipiscing elit.\n ++token: This is a very long value, with spaces and\n ++ newlines in it.\n +------------------------------------------------\n \n Note that trailers do not follow (nor are they intended to follow) many of the\n\n-- \ngitgitgadget\n"},{"id":"477090","messageId":"823534718313979920088729bb04b5d2433fa5c6.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 2/9] doc: trailer: swap verb order","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:28Z","receivedAt":"2023-05-11T21:19:46Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis matches the order already used in the NAME section.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 1a1d6288b17..cd4d724a0b7 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n+Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-- \ngitgitgadget\n\n"},{"id":"477091","messageId":"5fabe166714ba98c2583c35f2b25563248e90a6e.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 3/9] doc: trailer: drop \"commit message part\" phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:29Z","receivedAt":"2023-05-11T21:19:53Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe command can take inputs that are either just a commit message, or\nan email-like output such as git-format-patch which includes a commit\nmessage, \"---\" divider, and patch part. The existing explanation blends\nthese two inputs together in the first sentence\n\n This command reads some patches or commit messages\n\nwhich then necessitates using the \"commit message part\" phrasing (as\nopposed to just \"commit message\") because the input is ambiguous per the\nabove definition.\n\nThis change separates the two input types and explains them separately,\nand so there is no longer a need to use the \"commit message part\"\nphrase.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------\n 1 file changed, 19 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex cd4d724a0b7..58a7ea24606 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-This command reads some patches or commit messages from either the\n- arguments or the standard input if no is specified. If\n-`--parse` is specified, the output consists of the parsed trailers.\n-\n+This command reads commit messages from either the\n+ arguments or the standard input if no is specified.\n+If `--parse` is specified, the output consists of the parsed trailers.\n Otherwise, this command applies the arguments passed using the\n-`--trailer` option, if any, to the commit message part of each input\n-file. The result is emitted on the standard output.\n+`--trailer` option, if any, to each input file. The result is emitted on the\n+standard output.\n+\n+This command can also operate on the output of linkgit:git-format-patch[1],\n+which is more elaborate than a plain commit message. Namely, such output\n+includes a commit message (as above), a \"---\" divider line, and a patch part.\n+For these inputs, the divider and patch parts are ignored, unless `--no-divider`\n+is specified.\n \n Some configuration variables control the way the `--trailer` arguments\n-are applied to each commit message and the way any existing trailer in\n-the commit message is changed. They also make it possible to\n+are applied to each input and the way any existing trailer in\n+the input is changed. They also make it possible to\n automatically add some trailers.\n \n By default, a '=' or ':' argument given\n@@ -36,7 +41,7 @@ using `--trailer` will be appended after the existing trailers only if\n the last trailer has a different (, ) pair (or if there\n is no existing trailer). The and parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n- and will appear in the message like this:\n+ and will appear in the output like this:\n \n ------------------------------------------------\n token: value\n@@ -47,19 +52,17 @@ This means that the trimmed and will be separated by\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-after the commit message part of the output, and, if there is no line\n-with only spaces at the end of the commit message part, one blank line\n-will be added before the new trailer.\n+at the end of the input. A blank line will be added before the new\n+trailer if there isn't one already.\n \n-Existing trailers are extracted from the input message by looking for\n+Existing trailers are extracted from the input by looking for\n a group of one or more lines that (i) is all trailers, or (ii) contains at\n least one Git-generated or user-configured trailer and consists of at\n least 25% trailers.\n The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the message or be the last\n+The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with '---' (followed by a\n-space or the end of the line). Such three minus signs start the patch\n-part of the message. See also `--no-divider` below.\n+space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n token, but any number of regular space and tab characters are allowed\n-- \ngitgitgadget\n\n"},{"id":"477092","messageId":"dd7e29fcc214ee9cdb9737f5378bfde14465609f.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 5/9] doc: trailer: remove redundant phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:31Z","receivedAt":"2023-05-11T21:19:57Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe phrase \"many rules\" gets essentially repeated again with \"many other\nrules\", so remove this repetition.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 8766edbf4dc..495d5c9bcf1 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -71,9 +71,8 @@ inside or after the value. The value may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n-Note that 'trailers' do not follow and are not intended to follow many\n-rules for RFC 822 headers. For example they do not follow\n-the encoding rules and probably many other rules.\n+Note that trailers do not follow (nor are they intended to follow) many of the\n+rules for RFC 822 headers. For example they do not follow the encoding rule.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"477093","messageId":"96cb4ae2965772666457ea84cfc2cfc42e06bbf4.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 6/9] doc: trailer: use angle brackets for and ","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:32Z","receivedAt":"2023-05-11T21:19:58Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nWe already use angle brackets elsewhere, so this makes things more\nconsistent.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 495d5c9bcf1..576f5987b0d 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -65,9 +65,9 @@ non-whitespace lines before a line that starts with '---' (followed by a\n space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n-token, but any number of regular space and tab characters are allowed\n-between the token and the separator. There can be whitespaces before,\n-inside or after the value. The value may be split over multiple lines\n+, but any number of regular space and tab characters are allowed\n+between the and the separator. There can be whitespaces before,\n+inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n@@ -240,7 +240,7 @@ trailer..command::\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n-\tvalue that would be passed as argument.\n+\t that would be passed as argument.\n +\n The 'trailer..command' option has been deprecated in favor of\n 'trailer..cmd' due to the fact that $ARG in the user's command is\n-- \ngitgitgadget\n\n"},{"id":"477094","messageId":"783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 4/9] doc: trailer: examples: avoid the word \"message\" by itself","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:30Z","receivedAt":"2023-05-11T21:20:01Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nPreviously, \"message\" could mean the input, output, commit message, or\n\"internal body text inside the commit message\" (in the EXAMPLES\nsection). Avoid overloading this term by using the appropriate meanings\nexplicitly.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 42 ++++++++++++------------\n 1 file changed, 21 insertions(+), 21 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 58a7ea24606..8766edbf4dc 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -82,12 +82,12 @@ OPTIONS\n \n --trim-empty::\n \tIf the part of any trailer contains only whitespace,\n-\tthe whole trailer will be removed from the resulting message.\n+\tthe whole trailer will be removed from the output.\n \tThis applies to existing trailers as well as new trailers.\n \n --trailer [(=|:)]::\n \tSpecify a (, ) pair that should be applied as a\n-\ttrailer to the input messages. See the description of this\n+\ttrailer to the inputs. See the description of this\n \tcommand.\n \n --where ::\n@@ -101,7 +101,7 @@ OPTIONS\n --if-exists ::\n --no-if-exists::\n \tSpecify what action will be performed when there is already at\n-\tleast one trailer with the same in the message. A setting\n+\tleast one trailer with the same in the input. A setting\n \tprovided with '--if-exists' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,\n@@ -110,7 +110,7 @@ OPTIONS\n --if-missing ::\n --no-if-missing::\n \tSpecify what action will be performed when there is no other\n-\ttrailer with the same in the message. A setting\n+\ttrailer with the same in the input. A setting\n \tprovided with '--if-missing' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`\n@@ -177,7 +177,7 @@ first trailer with the same .\n trailer.ifexists::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is already at least one trailer with the\n-\tsame in the message.\n+\tsame in the input.\n +\n The valid values for this option are: `addIfDifferentNeighbor` (this\n is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.\n@@ -187,10 +187,10 @@ trailer with the same (, ) pair is above or below the line\n where the new trailer will be added.\n +\n With `addIfDifferent`, a new trailer will be added only if no trailer\n-with the same (, ) pair is already in the message.\n+with the same (, ) pair is already in the input.\n +\n With `add`, a new trailer will be added, even if some trailers with\n-the same (, ) pair are already in the message.\n+the same (, ) pair are already in the input.\n +\n With `replace`, an existing trailer with the same will be\n deleted and the new trailer will be added. The deleted trailer will be\n@@ -198,12 +198,12 @@ the closest one (with the same ) to the place where the new one\n will be added.\n +\n With `doNothing`, nothing will be done; that is no new trailer will be\n-added if there is already one with the same in the message.\n+added if there is already one with the same in the input.\n \n trailer.ifmissing::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is not yet any trailer with the same\n-\t in the message.\n+\t in the input.\n +\n The valid values for this option are: `add` (this is the default) and\n `doNothing`.\n@@ -275,37 +275,37 @@ EXAMPLES\n --------\n \n * Configure a 'sign' trailer with a 'Signed-off-by' key, and then\n- add two of these trailers to a message:\n+ add two of these trailers to a commit message file:\n +\n ------------\n $ git config trailer.sign.key \"Signed-off-by\"\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob '\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Alice \n Signed-off-by: Bob \n ------------\n \n-* Use the `--in-place` option to edit a message file in place:\n+* Use the `--in-place` option to edit a commit message file in place:\n +\n ------------\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Bob \n $ git interpret-trailers --trailer 'Acked-by: Alice ' --in-place msg.txt\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Bob \n Acked-by: Alice \n@@ -366,12 +366,12 @@ $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n $ git interpret-trailers --trailer=\"help:Junio\" --trailer=\"help:Couder\" < subject\n >\n-> message\n+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n >\n > EOF\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Helped-by: Junio C Hamano \n Helped-by: Christian Couder \n@@ -391,12 +391,12 @@ $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n $ git interpret-trailers --trailer=\"ref:Add copyright notices.\" < subject\n >\n-> message\n+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n >\n > EOF\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)\n ------------\n@@ -412,13 +412,13 @@ $ git config trailer.see.command \"git log -1 --oneline --format=\\\"%h (%s)\\\" --ab\n $ git interpret-trailers < subject\n > \n-> message\n+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n > \n > see: HEAD~2\n > EOF\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n See-also: fe3187489d69c4 (subject of related commit)\n ------------\n-- \ngitgitgadget\n\n"},{"id":"477095","messageId":"7e95198894b7de9b3d16dfa7d686b5fe3bced5b4.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 9/9] doc: trailer: add more examples in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:35Z","receivedAt":"2023-05-11T21:20:04Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nBe more up-front about what trailers are in practice with examples, to\ngive the reader a visual cue while they go on to read the rest of the\ndescription.\n\nAlso add an example for multiline values.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--\n 1 file changed, 18 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 245a66a7a85..e13a5ec6943 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -16,7 +16,18 @@ DESCRIPTION\n -----------\n Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n-message.\n+message. For example, in the following commit message\n+\n+------------------------------------------------\n+subject\n+\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n+\n+Signed-off-by: Alice \n+Signed-off-by: Bob \n+------------------------------------------------\n+\n+the last two lines starting with \"Signed-off-by\" are trailers.\n \n This command reads commit messages from either the\n arguments or the standard input if no is specified.\n@@ -71,7 +82,12 @@ When reading trailers, there can be no whitespace before or inside the\n between the and the separator. There can be whitespaces before,\n inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n-the \"folding\" in RFC 822.\n+the \"folding\" in RFC 822. Example:\n+\n+------------------------------------------------\n+token: This is a very long value, with spaces and\n+ newlines in it.\n+------------------------------------------------\n \n Note that trailers do not follow (nor are they intended to follow) many of the\n rules for RFC 822 headers. For example they do not follow the encoding rule.\n-- \ngitgitgadget\n"},{"id":"477096","messageId":"4e234110ffd2e6030f929b5179e62d722fcacb6d.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 7/9] doc: trailer..command: emphasize deprecation","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:33Z","receivedAt":"2023-05-11T21:20:08Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis puts the deprecation notice up front, instead of leaving it to the\nnext paragraph.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 576f5987b0d..32a26c59f8a 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -237,13 +237,13 @@ trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n+\tDeprecated in favor of 'trailer..cmd'.\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n \t that would be passed as argument.\n +\n-The 'trailer..command' option has been deprecated in favor of\n-'trailer..cmd' due to the fact that $ARG in the user's command is\n+Note that $ARG in the user's command is\n only replaced once and that the original way of replacing $ARG is not safe.\n +\n When both 'trailer..cmd' and 'trailer..command' are given\n-- \ngitgitgadget\n\n"},{"id":"477097","messageId":"8aaf9e27d98cc823efaa9032a07cb2994a3cae48.1683839975.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v2 8/9] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-05-11T21:19:34Z","receivedAt":"2023-05-11T21:20:10Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe 'key' option is used frequently in the examples at the bottom but\nthere is no mention of it in the description.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 32a26c59f8a..245a66a7a85 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -48,7 +48,9 @@ token: value\n ------------------------------------------------\n \n This means that the trimmed and will be separated by\n-`': '` (one colon followed by one space).\n+`': '` (one colon followed by one space). If the should have a different\n+string representation than itself, then the 'key' can be configured with\n+'trailer..key'.\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-- \ngitgitgadget\n\n"},{"id":"477240","messageId":"xmqqv8gxm8uj.fsf@gitster.g","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-12T23:24:36Z","receivedAt":"2023-05-12T23:24:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Linus Arver via GitGitGadget\" writes:\n\n> This series makes some small improvements to the docs for\n> git-interpret-trailers. The intent is to make it easier to read for\n> beginners who have never used this command before.\n>\n>\n> Changes from v1\n> ===============\n>\n> In order of significance:\n>\n> * The phrase \"commit message part\" has been removed.\n> * The word \"message\" is always used as part of the bigger phrase \"commit\n> message\".\n> * Deprecation language for trailer..command has been updated to\n> minimize whitespace churn, while also tweaking the 2nd paragraph to\n> reduce duplication.\n> * The phrase \"Lorem ipsum...\" is always only used to stand in for the body\n> paragraph(s) of a commit message.\n> * Grammar fixes have been squashed together (01+06 previously).\n\nLooking very good.\n\nUnfortunately some of the updates to examples overlap moderately\nwith what the kh/doc-interpret-trailers-updates topic wanted to do.\nI think I resolved them correctly, but please double check what\nappears in 'seen'.\n\nAs the other topic is slated to graduate in a day or two (topics\nusually cook for a week in 'next' before merged to 'master'), it\nmay be a good idea to wait for more review comments and then rebase\nthese patches on top of 'master' when that happens.\n\nThanks.\n"},{"id":"477421","messageId":"owlybkijnaug.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"xmqqv8gxm8uj.fsf@gitster.g","subject":"Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-05-16T22:57:27Z","receivedAt":"2023-05-16T22:57:35Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"\nJunio C Hamano writes:\n\n> Looking very good.\n\n> Unfortunately some of the updates to examples overlap moderately\n> with what the kh/doc-interpret-trailers-updates topic wanted to do.\n> I think I resolved them correctly, but please double check what\n> appears in 'seen'.\n\nI don't think I can double-check 'seen' in a timely manner (see \"FYI\"\nbelow).\n\n> As the other topic is slated to graduate in a day or two (topics\n> usually cook for a week in 'next' before merged to 'master'), it\n> may be a good idea to wait for more review comments and then rebase\n> these patches on top of 'master' when that happens.\n\nWill do. Thanks for the tip!\n\nFYI: I am currently on vacation (in hindsight I should have mentioned\nthis ahead of time) and won't be back until June 5. Still, I am highly\ninterested in seeing how my topic branch evolves (along with the\ninteractions with 'seen', 'next', etc) so I will at least have a look\ntime to time before my official @work return date to see if I can rebase\nthis topic on master when it (master) moves.\n"},{"id":"477423","messageId":"xmqqmt23sw5l.fsf@gitster.g","threadId":"59712","inReplyTo":"owlybkijnaug.fsf@fine.c.googlers.com","subject":"Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-16T23:18:14Z","receivedAt":"2023-05-16T23:18:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Arver writes:\n\n> FYI: I am currently on vacation (in hindsight I should have mentioned\n> this ahead of time) and won't be back until June 5. Still, I am highly\n> interested in seeing how my topic branch evolves (along with the\n> interactions with 'seen', 'next', etc) so I will at least have a look\n> time to time before my official @work return date to see if I can rebase\n> this topic on master when it (master) moves.\n\nThanks.\n\nFYI, we will go into a pre-release feature freeze when no new\n\"features\" or \"fixes\" will graduate to the 'master' branch, unless\nit is a regression fix to the change that happened between 2.40 and\n'master'. As the next release is planned for the beginning of June,\nyour vacation would coincide well with back-burnering the topic ;-)\n\nHave fun.\n"},{"id":"478062","messageId":"7d504700b91c175c952a16f0d82e642393ce7c84.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 1/9] doc: trailer: fix grammar","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:16Z","receivedAt":"2023-06-06T02:08:31Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 4b97f812be8..35faf837892 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n+Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n@@ -249,10 +249,10 @@ for the same , 'trailer..cmd' is used and\n 'trailer..command' is ignored.\n \n trailer..cmd::\n-\tThis option can be used to specify a shell command that will be called:\n+\tThis option can be used to specify a shell command that will be called\n \tonce to automatically add a trailer with the specified , and then\n-\teach time a '--trailer =' argument to modify the of\n-\tthe trailer that this option would produce.\n+\tcalled each time a '--trailer =' argument is specified to\n+\tmodify the of the trailer that this option would produce.\n +\n When the specified command is first called to add a trailer\n with the specified , the behavior is as if a special\n-- \ngitgitgadget\n\n"},{"id":"478063","messageId":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com","subject":"[PATCH v3 0/9] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:15Z","receivedAt":"2023-06-06T02:08:33Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"This series makes some small improvements to the docs for\ngit-interpret-trailers. The intent is to make it easier to read for\nbeginners who have never used this command before.\n\n\nChanges from v2 to v3\n=====================\n\n * Rebased on top of \"master\" at fe86abd751 (Git 2.41, 2023-06-01). The only\n conflict was in Patch v2 4/9\n (https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),\n because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)\n added the \"subject/message\" style for the examples that did not have any\n message text in them. These examples' additional message lines have been\n replaced with Lorem ipsum... like the others in Patch v2 4/9.\n\n\nChanges from v1 to v2\n=====================\n\nIn order of significance:\n\n * The phrase \"commit message part\" has been removed.\n * The word \"message\" is always used as part of the bigger phrase \"commit\n message\".\n * Deprecation language for trailer..command has been updated to\n minimize whitespace churn, while also tweaking the 2nd paragraph to\n reduce duplication.\n * The phrase \"Lorem ipsum...\" is always only used to stand in for the body\n paragraph(s) of a commit message.\n * Grammar fixes have been squashed together (01+06 previously).\n\nLinus Arver (9):\n doc: trailer: fix grammar\n doc: trailer: swap verb order\n doc: trailer: drop \"commit message part\" phrasing\n doc: trailer: examples: avoid the word \"message\" by itself\n doc: trailer: remove redundant phrasing\n doc: trailer: use angle brackets for and \n doc: trailer..command: emphasize deprecation\n doc: trailer: mention 'key' in DESCRIPTION\n doc: trailer: add more examples in DESCRIPTION\n\n Documentation/git-interpret-trailers.txt | 132 +++++++++++++----------\n 1 file changed, 76 insertions(+), 56 deletions(-)\n\n\nbase-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v3\nPull-Request: https://github.com/git/git/pull/1506\n\nRange-diff vs v2:\n\n 1: 65e6fbdec92 = 1: 7d504700b91 doc: trailer: fix grammar\n 2: 82353471831 = 2: 65386432ca4 doc: trailer: swap verb order\n 3: 5fabe166714 = 3: e0a56c8e61d doc: trailer: drop \"commit message part\" phrasing\n 4: 783a0b1e003 ! 4: 52f7d29f509 doc: trailer: examples: avoid the word \"message\" by itself\n @@ Documentation/git-interpret-trailers.txt: EXAMPLES\n \n -message\n +Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n - $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob '\n + $ git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob ' \n Acked-by: Alice \n -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n - $ git interpret-trailers --trailer=\"help:Junio\" --trailer=\"help:Couder\" < subject\n - >\n --> message\n -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n - >\n - > EOF\n +@@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc: Alice ' --trailer 'Re\n + $ cat msg1.txt\n + subject\n + \n +-message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n + $ git config trailer.sign.key \"Signed-off-by: \"\n + $ git config trailer.sign.ifmissing add\n + $ git config trailer.sign.ifexists doNothing\n +@@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo \"$(git config user.name) <$(git config user.\n + $ git interpret-trailers --trailer sign \n + $ cat msg2.txt\n + subject\n + \n +-message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n + \n + Signed-off-by: Alice \n + $ git interpret-trailers --trailer sign \n + ------------\n +@@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --author=\"$1\" --pretty=\"%an <%ae>\" -1 || true\n + $ cat msg.txt\n + subject\n + \n +-message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n + $ git config trailer.help.key \"Helped-by: \"\n + $ git config trailer.help.ifExists \"addIfDifferentNeighbor\"\n + $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n + $ git interpret-trailers --trailer=\"help:Junio\" --trailer=\"help:Couder\" \n Helped-by: Christian Couder \n -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n - $ git interpret-trailers --trailer=\"ref:Add copyright notices.\" < subject\n - >\n --> message\n -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n - >\n - > EOF\n +@@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --grep \"$1\" --pretty=reference -1 || true\n + $ cat msg.txt\n + subject\n + \n +-message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n + $ git config trailer.ref.key \"Reference-to: \"\n + $ git config trailer.ref.ifExists \"replace\"\n + $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n + $ git interpret-trailers --trailer=\"ref:Add copyright notices.\" subject\n - > \n --> message\n -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n - > \n - > see: HEAD~2\n - > EOF\n +@@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)\n + $ cat msg.txt\n + subject\n + \n +-message\n ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n + \n + see: HEAD~2\n + $ cat ~/bin/glog-ref\n +@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd \"glog-ref\"\n + $ git interpret-trailers --trailer=see and \n 7: 4e234110ffd = 7: 6aba774489a doc: trailer..command: emphasize deprecation\n 8: 8aaf9e27d98 = 8: b13bd73d248 doc: trailer: mention 'key' in DESCRIPTION\n 9: 7e95198894b = 9: ec43e192d6e doc: trailer: add more examples in DESCRIPTION\n\n-- \ngitgitgadget\n"},{"id":"478064","messageId":"65386432ca4a8a41acdb4f061a8ca6a8f02d289b.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 2/9] doc: trailer: swap verb order","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:17Z","receivedAt":"2023-06-06T02:08:35Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis matches the order already used in the NAME section.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 35faf837892..da8fec7d5fe 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n+Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-- \ngitgitgadget\n\n"},{"id":"478065","messageId":"e0a56c8e61d80ef345885bf266e9844de289695f.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 3/9] doc: trailer: drop \"commit message part\" phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:18Z","receivedAt":"2023-06-06T02:08:37Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe command can take inputs that are either just a commit message, or\nan email-like output such as git-format-patch which includes a commit\nmessage, \"---\" divider, and patch part. The existing explanation blends\nthese two inputs together in the first sentence\n\n This command reads some patches or commit messages\n\nwhich then necessitates using the \"commit message part\" phrasing (as\nopposed to just \"commit message\") because the input is ambiguous per the\nabove definition.\n\nThis change separates the two input types and explains them separately,\nand so there is no longer a need to use the \"commit message part\"\nphrase.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------\n 1 file changed, 19 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex da8fec7d5fe..ffde97a6c3d 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-This command reads some patches or commit messages from either the\n- arguments or the standard input if no is specified. If\n-`--parse` is specified, the output consists of the parsed trailers.\n-\n+This command reads commit messages from either the\n+ arguments or the standard input if no is specified.\n+If `--parse` is specified, the output consists of the parsed trailers.\n Otherwise, this command applies the arguments passed using the\n-`--trailer` option, if any, to the commit message part of each input\n-file. The result is emitted on the standard output.\n+`--trailer` option, if any, to each input file. The result is emitted on the\n+standard output.\n+\n+This command can also operate on the output of linkgit:git-format-patch[1],\n+which is more elaborate than a plain commit message. Namely, such output\n+includes a commit message (as above), a \"---\" divider line, and a patch part.\n+For these inputs, the divider and patch parts are ignored, unless `--no-divider`\n+is specified.\n \n Some configuration variables control the way the `--trailer` arguments\n-are applied to each commit message and the way any existing trailer in\n-the commit message is changed. They also make it possible to\n+are applied to each input and the way any existing trailer in\n+the input is changed. They also make it possible to\n automatically add some trailers.\n \n By default, a '=' or ':' argument given\n@@ -36,7 +41,7 @@ using `--trailer` will be appended after the existing trailers only if\n the last trailer has a different (, ) pair (or if there\n is no existing trailer). The and parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n- and will appear in the message like this:\n+ and will appear in the output like this:\n \n ------------------------------------------------\n token: value\n@@ -47,19 +52,17 @@ This means that the trimmed and will be separated by\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-after the commit message part of the output, and, if there is no line\n-with only spaces at the end of the commit message part, one blank line\n-will be added before the new trailer.\n+at the end of the input. A blank line will be added before the new\n+trailer if there isn't one already.\n \n-Existing trailers are extracted from the input message by looking for\n+Existing trailers are extracted from the input by looking for\n a group of one or more lines that (i) is all trailers, or (ii) contains at\n least one Git-generated or user-configured trailer and consists of at\n least 25% trailers.\n The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the message or be the last\n+The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with '---' (followed by a\n-space or the end of the line). Such three minus signs start the patch\n-part of the message. See also `--no-divider` below.\n+space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n token, but any number of regular space and tab characters are allowed\n-- \ngitgitgadget\n\n"},{"id":"478066","messageId":"52f7d29f509070a17a32a6f1c888588cc87e6cb9.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 4/9] doc: trailer: examples: avoid the word \"message\" by itself","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:19Z","receivedAt":"2023-06-06T02:08:39Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nPreviously, \"message\" could mean the input, output, commit message, or\n\"internal body text inside the commit message\" (in the EXAMPLES\nsection). Avoid overloading this term by using the appropriate meanings\nexplicitly.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------\n 1 file changed, 25 insertions(+), 25 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex ffde97a6c3d..011ed0c3590 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -82,12 +82,12 @@ OPTIONS\n \n --trim-empty::\n \tIf the part of any trailer contains only whitespace,\n-\tthe whole trailer will be removed from the resulting message.\n+\tthe whole trailer will be removed from the output.\n \tThis applies to existing trailers as well as new trailers.\n \n --trailer [(=|:)]::\n \tSpecify a (, ) pair that should be applied as a\n-\ttrailer to the input messages. See the description of this\n+\ttrailer to the inputs. See the description of this\n \tcommand.\n \n --where ::\n@@ -101,7 +101,7 @@ OPTIONS\n --if-exists ::\n --no-if-exists::\n \tSpecify what action will be performed when there is already at\n-\tleast one trailer with the same in the message. A setting\n+\tleast one trailer with the same in the input. A setting\n \tprovided with '--if-exists' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,\n@@ -110,7 +110,7 @@ OPTIONS\n --if-missing ::\n --no-if-missing::\n \tSpecify what action will be performed when there is no other\n-\ttrailer with the same in the message. A setting\n+\ttrailer with the same in the input. A setting\n \tprovided with '--if-missing' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`\n@@ -177,7 +177,7 @@ first trailer with the same .\n trailer.ifexists::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is already at least one trailer with the\n-\tsame in the message.\n+\tsame in the input.\n +\n The valid values for this option are: `addIfDifferentNeighbor` (this\n is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.\n@@ -187,10 +187,10 @@ trailer with the same (, ) pair is above or below the line\n where the new trailer will be added.\n +\n With `addIfDifferent`, a new trailer will be added only if no trailer\n-with the same (, ) pair is already in the message.\n+with the same (, ) pair is already in the input.\n +\n With `add`, a new trailer will be added, even if some trailers with\n-the same (, ) pair are already in the message.\n+the same (, ) pair are already in the input.\n +\n With `replace`, an existing trailer with the same will be\n deleted and the new trailer will be added. The deleted trailer will be\n@@ -198,12 +198,12 @@ the closest one (with the same ) to the place where the new one\n will be added.\n +\n With `doNothing`, nothing will be done; that is no new trailer will be\n-added if there is already one with the same in the message.\n+added if there is already one with the same in the input.\n \n trailer.ifmissing::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is not yet any trailer with the same\n-\t in the message.\n+\t in the input.\n +\n The valid values for this option are: `add` (this is the default) and\n `doNothing`.\n@@ -275,37 +275,37 @@ EXAMPLES\n --------\n \n * Configure a 'sign' trailer with a 'Signed-off-by' key, and then\n- add two of these trailers to a message:\n+ add two of these trailers to a commit message file:\n +\n ------------\n $ git config trailer.sign.key \"Signed-off-by\"\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n $ git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob ' \n Signed-off-by: Bob \n ------------\n \n-* Use the `--in-place` option to edit a message file in place:\n+* Use the `--in-place` option to edit a commit message file in place:\n +\n ------------\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Bob \n $ git interpret-trailers --trailer 'Acked-by: Alice ' --in-place msg.txt\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Bob \n Acked-by: Alice \n@@ -328,7 +328,7 @@ $ git interpret-trailers --trailer 'Cc: Alice ' --trailer 'Re\n $ cat msg1.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n $ git config trailer.sign.key \"Signed-off-by: \"\n $ git config trailer.sign.ifmissing add\n $ git config trailer.sign.ifexists doNothing\n@@ -336,19 +336,19 @@ $ git config trailer.sign.cmd 'echo \"$(git config user.name) <$(git config user.\n $ git interpret-trailers --trailer sign \n $ cat msg2.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n \n Signed-off-by: Alice \n $ git interpret-trailers --trailer sign \n ------------\n@@ -376,14 +376,14 @@ test -n \"$1\" && git log --author=\"$1\" --pretty=\"%an <%ae>\" -1 || true\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n $ git config trailer.help.key \"Helped-by: \"\n $ git config trailer.help.ifExists \"addIfDifferentNeighbor\"\n $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n $ git interpret-trailers --trailer=\"help:Junio\" --trailer=\"help:Couder\" \n Helped-by: Christian Couder \n@@ -400,14 +400,14 @@ test -n \"$1\" && git log --grep \"$1\" --pretty=reference -1 || true\n $ cat msg.txt\n subject\n \n-message\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n $ git config trailer.ref.key \"Reference-to: \"\n $ git config trailer.ref.ifExists \"replace\"\n $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n $ git interpret-trailers --trailer=\"ref:Add copyright notices.\" \n\nThe phrase \"many rules\" gets essentially repeated again with \"many other\nrules\", so remove this repetition.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 011ed0c3590..d1d3e50bde7 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -71,9 +71,8 @@ inside or after the value. The value may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n-Note that 'trailers' do not follow and are not intended to follow many\n-rules for RFC 822 headers. For example they do not follow\n-the encoding rules and probably many other rules.\n+Note that trailers do not follow (nor are they intended to follow) many of the\n+rules for RFC 822 headers. For example they do not follow the encoding rule.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"478068","messageId":"f99545409dc66187ae7995238958cc10ae508c03.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 6/9] doc: trailer: use angle brackets for and ","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:21Z","receivedAt":"2023-06-06T02:08:44Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nWe already use angle brackets elsewhere, so this makes things more\nconsistent.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex d1d3e50bde7..d69851dd367 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -65,9 +65,9 @@ non-whitespace lines before a line that starts with '---' (followed by a\n space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n-token, but any number of regular space and tab characters are allowed\n-between the token and the separator. There can be whitespaces before,\n-inside or after the value. The value may be split over multiple lines\n+, but any number of regular space and tab characters are allowed\n+between the and the separator. There can be whitespaces before,\n+inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n@@ -240,7 +240,7 @@ trailer..command::\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n-\tvalue that would be passed as argument.\n+\t that would be passed as argument.\n +\n The 'trailer..command' option has been deprecated in favor of\n 'trailer..cmd' due to the fact that $ARG in the user's command is\n-- \ngitgitgadget\n\n"},{"id":"478069","messageId":"6aba774489a2a0f4f7a2c52a71cbe1f8d2b6a686.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 7/9] doc: trailer..command: emphasize deprecation","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:22Z","receivedAt":"2023-06-06T02:08:45Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis puts the deprecation notice up front, instead of leaving it to the\nnext paragraph.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex d69851dd367..b034784e1d8 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -237,13 +237,13 @@ trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n+\tDeprecated in favor of 'trailer..cmd'.\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n \t that would be passed as argument.\n +\n-The 'trailer..command' option has been deprecated in favor of\n-'trailer..cmd' due to the fact that $ARG in the user's command is\n+Note that $ARG in the user's command is\n only replaced once and that the original way of replacing $ARG is not safe.\n +\n When both 'trailer..cmd' and 'trailer..command' are given\n-- \ngitgitgadget\n\n"},{"id":"478070","messageId":"b13bd73d24885d65440e22202183bbec9deec1c5.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:23Z","receivedAt":"2023-06-06T02:08:47Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe 'key' option is used frequently in the examples at the bottom but\nthere is no mention of it in the description.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex b034784e1d8..2e92640543c 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -48,7 +48,9 @@ token: value\n ------------------------------------------------\n \n This means that the trimmed and will be separated by\n-`': '` (one colon followed by one space).\n+`': '` (one colon followed by one space). If the should have a different\n+string representation than itself, then the 'key' can be configured with\n+'trailer..key'.\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-- \ngitgitgadget\n\n"},{"id":"478071","messageId":"ec43e192d6eae0daa70c8cbf3a35bcee2f4b38af.1686017304.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v3 9/9] doc: trailer: add more examples in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-06T02:08:24Z","receivedAt":"2023-06-06T02:08:48Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nBe more up-front about what trailers are in practice with examples, to\ngive the reader a visual cue while they go on to read the rest of the\ndescription.\n\nAlso add an example for multiline values.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--\n 1 file changed, 18 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 2e92640543c..2e999320ec6 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -16,7 +16,18 @@ DESCRIPTION\n -----------\n Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n-message.\n+message. For example, in the following commit message\n+\n+------------------------------------------------\n+subject\n+\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n+\n+Signed-off-by: Alice \n+Signed-off-by: Bob \n+------------------------------------------------\n+\n+the last two lines starting with \"Signed-off-by\" are trailers.\n \n This command reads commit messages from either the\n arguments or the standard input if no is specified.\n@@ -71,7 +82,12 @@ When reading trailers, there can be no whitespace before or inside the\n between the and the separator. There can be whitespaces before,\n inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n-the \"folding\" in RFC 822.\n+the \"folding\" in RFC 822. Example:\n+\n+------------------------------------------------\n+token: This is a very long value, with spaces and\n+ newlines in it.\n+------------------------------------------------\n \n Note that trailers do not follow (nor are they intended to follow) many of the\n rules for RFC 822 headers. For example they do not follow the encoding rule.\n-- \ngitgitgadget\n"},{"id":"478369","messageId":"CAP8UFD2iej1EhUtR=+wqcnnoYrwCPFoR2ed71Wswyd8CYPthFA@mail.gmail.com","threadId":"59712","inReplyTo":"e0a56c8e61d80ef345885bf266e9844de289695f.1686017304.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 3/9] doc: trailer: drop \"commit message part\" phrasing","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2023-06-14T15:00:31Z","receivedAt":"2023-06-14T15:00:49Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget\n wrote:\n>\n> From: Linus Arver \n>\n> The command can take inputs that are either just a commit message, or\n> an email-like output such as git-format-patch which includes a commit\n> message, \"---\" divider, and patch part. The existing explanation blends\n> these two inputs together in the first sentence\n>\n> This command reads some patches or commit messages\n>\n> which then necessitates using the \"commit message part\" phrasing (as\n> opposed to just \"commit message\") because the input is ambiguous per the\n> above definition.\n>\n> This change separates the two input types and explains them separately,\n> and so there is no longer a need to use the \"commit message part\"\n> phrase.\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------\n> 1 file changed, 19 insertions(+), 16 deletions(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index da8fec7d5fe..ffde97a6c3d 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n> headers, at the end of the otherwise free-form part of a commit\n> message.\n>\n> -This command reads some patches or commit messages from either the\n> - arguments or the standard input if no is specified. If\n> -`--parse` is specified, the output consists of the parsed trailers.\n> -\n> +This command reads commit messages from either the\n> + arguments or the standard input if no is specified.\n> +If `--parse` is specified, the output consists of the parsed trailers.\n> Otherwise, this command applies the arguments passed using the\n> -`--trailer` option, if any, to the commit message part of each input\n> -file. The result is emitted on the standard output.\n> +`--trailer` option, if any, to each input file. The result is emitted on the\n> +standard output.\n> +\n> +This command can also operate on the output of linkgit:git-format-patch[1],\n> +which is more elaborate than a plain commit message. Namely, such output\n> +includes a commit message (as above), a \"---\" divider line, and a patch part.\n> +For these inputs, the divider and patch parts are ignored, unless `--no-divider`\n> +is specified.\n\nI think saying \"the divider and patch parts are ignored\" is a bit\nambiguous. It could mean that when a patch is read by the command only\nits commit message, possibly modified by the command, is emitted on\nthe standard output.\n\nI would suggest something like:\n\n\"For these inputs, the divider and patch parts are not modified by\nthis command and are emitted as is on the output, unless\n`--no-divider` is specified.\"\n"},{"id":"478370","messageId":"CAP8UFD30qxHdyeOKXOuP7cE-9VB4f2mLWB2DLZz2Vskwt4QBDw@mail.gmail.com","threadId":"59712","inReplyTo":"52f7d29f509070a17a32a6f1c888588cc87e6cb9.1686017304.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word \"message\" by itself","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2023-06-14T15:12:10Z","receivedAt":"2023-06-14T15:12:27Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"> $ git config trailer.sign.key \"Signed-off-by\"\n> $ cat msg.txt\n> subject\n>\n> -message\n> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\nI am not sure this change is clarifying anything. If you want\nsomething clearer for \"internal body text inside the commit message\",\nyou could perhaps just use \"body\" or \"body text\".\n\nI am not against using such latin words, but then why only in the body\nand not in the subject too? And if it's used in the subject too, then\nI am not sure it will make it easy for users to understand that the\nexample is using a simple commit message.\n"},{"id":"478371","messageId":"CAP8UFD3ikE8k7TJnX7wOt9K3JAhkh4chB3Gjp1B2tofU81xXWg@mail.gmail.com","threadId":"59712","inReplyTo":"b13bd73d24885d65440e22202183bbec9deec1c5.1686017304.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2023-06-14T15:27:22Z","receivedAt":"2023-06-14T15:27:51Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget\n wrote:\n>\n> From: Linus Arver \n>\n> The 'key' option is used frequently in the examples at the bottom but\n> there is no mention of it in the description.\n>\n> Signed-off-by: Linus Arver \n> ---\n> Documentation/git-interpret-trailers.txt | 4 +++-\n> 1 file changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\n> index b034784e1d8..2e92640543c 100644\n> --- a/Documentation/git-interpret-trailers.txt\n> +++ b/Documentation/git-interpret-trailers.txt\n> @@ -48,7 +48,9 @@ token: value\n> ------------------------------------------------\n>\n> This means that the trimmed and will be separated by\n> -`': '` (one colon followed by one space).\n> +`': '` (one colon followed by one space). If the should have a different\n> +string representation than itself, then the 'key' can be configured with\n> +'trailer..key'.\n\nI would rather say something like:\n\n\"A can be a shortcut name, for example \"sign\", instead of the\nfull string, for example \"Signed-off-by\", which should appear before\nthe separator on the output. This can be configured using the\n'trailer..key' configuration variable.\"\n"},{"id":"478373","messageId":"CAP8UFD1uTFCMoh9SnxNpRkvAK=6_VLLo_7yH5tuqS2auyX5G4Q@mail.gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2023-06-14T15:36:25Z","receivedAt":"2023-06-14T15:36:43Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget\n wrote:\n>\n> This series makes some small improvements to the docs for\n> git-interpret-trailers. The intent is to make it easier to read for\n> beginners who have never used this command before.\n\nThanks, and sorry for the late review. I found a few things that I\nthink could be improved, but I like the direction.\n"},{"id":"478409","messageId":"7d504700b91c175c952a16f0d82e642393ce7c84.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 1/9] doc: trailer: fix grammar","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:42Z","receivedAt":"2023-06-15T02:53:57Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 4b97f812be8..35faf837892 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail\n+Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n@@ -249,10 +249,10 @@ for the same , 'trailer..cmd' is used and\n 'trailer..command' is ignored.\n \n trailer..cmd::\n-\tThis option can be used to specify a shell command that will be called:\n+\tThis option can be used to specify a shell command that will be called\n \tonce to automatically add a trailer with the specified , and then\n-\teach time a '--trailer =' argument to modify the of\n-\tthe trailer that this option would produce.\n+\tcalled each time a '--trailer =' argument is specified to\n+\tmodify the of the trailer that this option would produce.\n +\n When the specified command is first called to add a trailer\n with the specified , the behavior is as if a special\n-- \ngitgitgadget\n\n"},{"id":"478410","messageId":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com","subject":"[PATCH v4 0/9] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:41Z","receivedAt":"2023-06-15T02:53:59Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"This series makes some small improvements to the docs for\ngit-interpret-trailers. The intent is to make it easier to read for\nbeginners who have never used this command before.\n\n\nUpdates in v4\n=============\n\n * vs Patch v3 3/9: Reworded a sentence to avoid ambiguity with the word\n \"ignored\".\n * vs Patch v3 4/9: Replaced \"Lorem ipsum...\" in favor of \"body text\" which\n is shorter and more obvious (and search-friendly).\n * vs Patch v3 8/9: Expanded the explanation about 'trailer..key' and its\n convenience, instead of only stating how to use this option.\n\n\nUpdates in v3\n=============\n\n * Rebased on top of \"master\" at fe86abd751 (Git 2.41, 2023-06-01). The only\n conflict was in Patch v2 4/9\n (https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),\n because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)\n added the \"subject/message\" style for the examples that did not have any\n message text in them. These examples' additional message lines have been\n replaced with Lorem ipsum... like the others in Patch v2 4/9.\n\n\nUpdates in v2\n=============\n\nIn order of significance:\n\n * The phrase \"commit message part\" has been removed.\n * The word \"message\" is always used as part of the bigger phrase \"commit\n message\".\n * Deprecation language for trailer..command has been updated to\n minimize whitespace churn, while also tweaking the 2nd paragraph to\n reduce duplication.\n * The phrase \"Lorem ipsum...\" is always only used to stand in for the body\n paragraph(s) of a commit message.\n * Grammar fixes have been squashed together (01+06 previously).\n\nLinus Arver (9):\n doc: trailer: fix grammar\n doc: trailer: swap verb order\n doc: trailer: drop \"commit message part\" phrasing\n doc: trailer: examples: avoid the word \"message\" by itself\n doc: trailer: remove redundant phrasing\n doc: trailer: use angle brackets for and \n doc: trailer..command: emphasize deprecation\n doc: trailer: mention 'key' in DESCRIPTION\n doc: trailer: add more examples in DESCRIPTION\n\n Documentation/git-interpret-trailers.txt | 134 +++++++++++++----------\n 1 file changed, 78 insertions(+), 56 deletions(-)\n\n\nbase-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v4\nPull-Request: https://github.com/git/git/pull/1506\n\nRange-diff vs v3:\n\n 1: 7d504700b91 = 1: 7d504700b91 doc: trailer: fix grammar\n 2: 65386432ca4 = 2: 65386432ca4 doc: trailer: swap verb order\n 3: e0a56c8e61d ! 3: 3c85477d791 doc: trailer: drop \"commit message part\" phrasing\n @@ Documentation/git-interpret-trailers.txt: Add or parse 'trailer' lines that look\n +This command can also operate on the output of linkgit:git-format-patch[1],\n +which is more elaborate than a plain commit message. Namely, such output\n +includes a commit message (as above), a \"---\" divider line, and a patch part.\n -+For these inputs, the divider and patch parts are ignored, unless `--no-divider`\n -+is specified.\n ++For these inputs, the divider and patch parts are not modified by\n ++this command and are emitted as is on the output, unless\n ++`--no-divider` is specified.\n \n Some configuration variables control the way the `--trailer` arguments\n -are applied to each commit message and the way any existing trailer in\n 4: 52f7d29f509 ! 4: 6b4cb31b170 doc: trailer: examples: avoid the word \"message\" by itself\n @@ Documentation/git-interpret-trailers.txt: EXAMPLES\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n $ git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob ' \n Signed-off-by: Bob \n @@ Documentation/git-interpret-trailers.txt: EXAMPLES\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Signed-off-by: Bob \n $ git interpret-trailers --trailer 'Acked-by: Alice ' --in-place msg.txt\n @@ Documentation/git-interpret-trailers.txt: EXAMPLES\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Signed-off-by: Bob \n Acked-by: Alice \n @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n $ git config trailer.sign.key \"Signed-off-by: \"\n $ git config trailer.sign.ifmissing add\n $ git config trailer.sign.ifexists doNothing\n @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo \"$\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Signed-off-by: Bob \n $ cat msg2.txt\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Signed-off-by: Alice \n $ git interpret-trailers --trailer sign \n ------------\n @@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --author=\"$1\"\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n $ git config trailer.help.key \"Helped-by: \"\n $ git config trailer.help.ifExists \"addIfDifferentNeighbor\"\n $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n @@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --author=\"$1\"\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Helped-by: Junio C Hamano \n Helped-by: Christian Couder \n @@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --grep \"$1\" --\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n $ git config trailer.ref.key \"Reference-to: \"\n $ git config trailer.ref.ifExists \"replace\"\n $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n @@ Documentation/git-interpret-trailers.txt: test -n \"$1\" && git log --grep \"$1\" --\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)\n ------------\n @@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n see: HEAD~2\n $ cat ~/bin/glog-ref\n @@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd \"glog-ref\n subject\n \n -message\n -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n ++body text\n \n See-also: fe3187489d69c4 (subject of related commit)\n ------------\n 5: 4a2a0e41e4a = 5: a4a2ed16dcc doc: trailer: remove redundant phrasing\n 6: f99545409dc = 6: 7a96d0705b9 doc: trailer: use angle brackets for and \n 7: 6aba774489a = 7: f67458a3660 doc: trailer..command: emphasize deprecation\n 8: b13bd73d248 ! 8: 604265c54df doc: trailer: mention 'key' in DESCRIPTION\n @@ Documentation/git-interpret-trailers.txt: token: value\n \n This means that the trimmed and will be separated by\n -`': '` (one colon followed by one space).\n -+`': '` (one colon followed by one space). If the should have a different\n -+string representation than itself, then the 'key' can be configured with\n -+'trailer..key'.\n ++`': '` (one colon followed by one space). For convenience, the can be a\n ++shortened string key (e.g., \"sign\") instead of the full string which should\n ++appear before the separator on the output (e.g., \"Signed-off-by\"). This can be\n ++configured using the 'trailer..key' configuration variable.\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n 9: ec43e192d6e = 9: 1a3755eacbe doc: trailer: add more examples in DESCRIPTION\n\n-- \ngitgitgadget\n"},{"id":"478411","messageId":"65386432ca4a8a41acdb4f061a8ca6a8f02d289b.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 2/9] doc: trailer: swap verb order","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:43Z","receivedAt":"2023-06-15T02:54:01Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis matches the order already used in the NAME section.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 35faf837892..da8fec7d5fe 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Parse or add 'trailer' lines that look similar to RFC 822 e-mail\n+Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-- \ngitgitgadget\n\n"},{"id":"478412","messageId":"3c85477d791d04b063e1f041c138c307e0ee495f.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 3/9] doc: trailer: drop \"commit message part\" phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:44Z","receivedAt":"2023-06-15T02:54:03Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe command can take inputs that are either just a commit message, or\nan email-like output such as git-format-patch which includes a commit\nmessage, \"---\" divider, and patch part. The existing explanation blends\nthese two inputs together in the first sentence\n\n This command reads some patches or commit messages\n\nwhich then necessitates using the \"commit message part\" phrasing (as\nopposed to just \"commit message\") because the input is ambiguous per the\nabove definition.\n\nThis change separates the two input types and explains them separately,\nand so there is no longer a need to use the \"commit message part\"\nphrase.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 36 +++++++++++++-----------\n 1 file changed, 20 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex da8fec7d5fe..d0a0b303880 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -18,17 +18,23 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n message.\n \n-This command reads some patches or commit messages from either the\n- arguments or the standard input if no is specified. If\n-`--parse` is specified, the output consists of the parsed trailers.\n-\n+This command reads commit messages from either the\n+ arguments or the standard input if no is specified.\n+If `--parse` is specified, the output consists of the parsed trailers.\n Otherwise, this command applies the arguments passed using the\n-`--trailer` option, if any, to the commit message part of each input\n-file. The result is emitted on the standard output.\n+`--trailer` option, if any, to each input file. The result is emitted on the\n+standard output.\n+\n+This command can also operate on the output of linkgit:git-format-patch[1],\n+which is more elaborate than a plain commit message. Namely, such output\n+includes a commit message (as above), a \"---\" divider line, and a patch part.\n+For these inputs, the divider and patch parts are not modified by\n+this command and are emitted as is on the output, unless\n+`--no-divider` is specified.\n \n Some configuration variables control the way the `--trailer` arguments\n-are applied to each commit message and the way any existing trailer in\n-the commit message is changed. They also make it possible to\n+are applied to each input and the way any existing trailer in\n+the input is changed. They also make it possible to\n automatically add some trailers.\n \n By default, a '=' or ':' argument given\n@@ -36,7 +42,7 @@ using `--trailer` will be appended after the existing trailers only if\n the last trailer has a different (, ) pair (or if there\n is no existing trailer). The and parts will be trimmed\n to remove starting and trailing whitespace, and the resulting trimmed\n- and will appear in the message like this:\n+ and will appear in the output like this:\n \n ------------------------------------------------\n token: value\n@@ -47,19 +53,17 @@ This means that the trimmed and will be separated by\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-after the commit message part of the output, and, if there is no line\n-with only spaces at the end of the commit message part, one blank line\n-will be added before the new trailer.\n+at the end of the input. A blank line will be added before the new\n+trailer if there isn't one already.\n \n-Existing trailers are extracted from the input message by looking for\n+Existing trailers are extracted from the input by looking for\n a group of one or more lines that (i) is all trailers, or (ii) contains at\n least one Git-generated or user-configured trailer and consists of at\n least 25% trailers.\n The group must be preceded by one or more empty (or whitespace-only) lines.\n-The group must either be at the end of the message or be the last\n+The group must either be at the end of the input or be the last\n non-whitespace lines before a line that starts with '---' (followed by a\n-space or the end of the line). Such three minus signs start the patch\n-part of the message. See also `--no-divider` below.\n+space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n token, but any number of regular space and tab characters are allowed\n-- \ngitgitgadget\n\n"},{"id":"478413","messageId":"a4a2ed16dcce9cd01b46d01661fcbce80413e2fb.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 5/9] doc: trailer: remove redundant phrasing","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:46Z","receivedAt":"2023-06-15T02:54:07Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe phrase \"many rules\" gets essentially repeated again with \"many other\nrules\", so remove this repetition.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 58a9c691492..7516593c470 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -72,9 +72,8 @@ inside or after the value. The value may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n-Note that 'trailers' do not follow and are not intended to follow many\n-rules for RFC 822 headers. For example they do not follow\n-the encoding rules and probably many other rules.\n+Note that trailers do not follow (nor are they intended to follow) many of the\n+rules for RFC 822 headers. For example they do not follow the encoding rule.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"478414","messageId":"6b4cb31b17077181a311ca87e82464a1e2ad67dd.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 4/9] doc: trailer: examples: avoid the word \"message\" by itself","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:45Z","receivedAt":"2023-06-15T02:54:08Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nPreviously, \"message\" could mean the input, output, commit message, or\n\"internal body text inside the commit message\" (in the EXAMPLES\nsection). Avoid overloading this term by using the appropriate meanings\nexplicitly.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------\n 1 file changed, 25 insertions(+), 25 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex d0a0b303880..58a9c691492 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -83,12 +83,12 @@ OPTIONS\n \n --trim-empty::\n \tIf the part of any trailer contains only whitespace,\n-\tthe whole trailer will be removed from the resulting message.\n+\tthe whole trailer will be removed from the output.\n \tThis applies to existing trailers as well as new trailers.\n \n --trailer [(=|:)]::\n \tSpecify a (, ) pair that should be applied as a\n-\ttrailer to the input messages. See the description of this\n+\ttrailer to the inputs. See the description of this\n \tcommand.\n \n --where ::\n@@ -102,7 +102,7 @@ OPTIONS\n --if-exists ::\n --no-if-exists::\n \tSpecify what action will be performed when there is already at\n-\tleast one trailer with the same in the message. A setting\n+\tleast one trailer with the same in the input. A setting\n \tprovided with '--if-exists' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,\n@@ -111,7 +111,7 @@ OPTIONS\n --if-missing ::\n --no-if-missing::\n \tSpecify what action will be performed when there is no other\n-\ttrailer with the same in the message. A setting\n+\ttrailer with the same in the input. A setting\n \tprovided with '--if-missing' overrides all configuration variables\n \tand applies to all '--trailer' options until the next occurrence of\n \t'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`\n@@ -178,7 +178,7 @@ first trailer with the same .\n trailer.ifexists::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is already at least one trailer with the\n-\tsame in the message.\n+\tsame in the input.\n +\n The valid values for this option are: `addIfDifferentNeighbor` (this\n is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.\n@@ -188,10 +188,10 @@ trailer with the same (, ) pair is above or below the line\n where the new trailer will be added.\n +\n With `addIfDifferent`, a new trailer will be added only if no trailer\n-with the same (, ) pair is already in the message.\n+with the same (, ) pair is already in the input.\n +\n With `add`, a new trailer will be added, even if some trailers with\n-the same (, ) pair are already in the message.\n+the same (, ) pair are already in the input.\n +\n With `replace`, an existing trailer with the same will be\n deleted and the new trailer will be added. The deleted trailer will be\n@@ -199,12 +199,12 @@ the closest one (with the same ) to the place where the new one\n will be added.\n +\n With `doNothing`, nothing will be done; that is no new trailer will be\n-added if there is already one with the same in the message.\n+added if there is already one with the same in the input.\n \n trailer.ifmissing::\n \tThis option makes it possible to choose what action will be\n \tperformed when there is not yet any trailer with the same\n-\t in the message.\n+\t in the input.\n +\n The valid values for this option are: `add` (this is the default) and\n `doNothing`.\n@@ -276,37 +276,37 @@ EXAMPLES\n --------\n \n * Configure a 'sign' trailer with a 'Signed-off-by' key, and then\n- add two of these trailers to a message:\n+ add two of these trailers to a commit message file:\n +\n ------------\n $ git config trailer.sign.key \"Signed-off-by\"\n $ cat msg.txt\n subject\n \n-message\n+body text\n $ git interpret-trailers --trailer 'sign: Alice ' --trailer 'sign: Bob ' \n Signed-off-by: Bob \n ------------\n \n-* Use the `--in-place` option to edit a message file in place:\n+* Use the `--in-place` option to edit a commit message file in place:\n +\n ------------\n $ cat msg.txt\n subject\n \n-message\n+body text\n \n Signed-off-by: Bob \n $ git interpret-trailers --trailer 'Acked-by: Alice ' --in-place msg.txt\n $ cat msg.txt\n subject\n \n-message\n+body text\n \n Signed-off-by: Bob \n Acked-by: Alice \n@@ -329,7 +329,7 @@ $ git interpret-trailers --trailer 'Cc: Alice ' --trailer 'Re\n $ cat msg1.txt\n subject\n \n-message\n+body text\n $ git config trailer.sign.key \"Signed-off-by: \"\n $ git config trailer.sign.ifmissing add\n $ git config trailer.sign.ifexists doNothing\n@@ -337,19 +337,19 @@ $ git config trailer.sign.cmd 'echo \"$(git config user.name) <$(git config user.\n $ git interpret-trailers --trailer sign \n $ cat msg2.txt\n subject\n \n-message\n+body text\n \n Signed-off-by: Alice \n $ git interpret-trailers --trailer sign \n ------------\n@@ -377,14 +377,14 @@ test -n \"$1\" && git log --author=\"$1\" --pretty=\"%an <%ae>\" -1 || true\n $ cat msg.txt\n subject\n \n-message\n+body text\n $ git config trailer.help.key \"Helped-by: \"\n $ git config trailer.help.ifExists \"addIfDifferentNeighbor\"\n $ git config trailer.help.cmd \"~/bin/glog-find-author\"\n $ git interpret-trailers --trailer=\"help:Junio\" --trailer=\"help:Couder\" \n Helped-by: Christian Couder \n@@ -401,14 +401,14 @@ test -n \"$1\" && git log --grep \"$1\" --pretty=reference -1 || true\n $ cat msg.txt\n subject\n \n-message\n+body text\n $ git config trailer.ref.key \"Reference-to: \"\n $ git config trailer.ref.ifExists \"replace\"\n $ git config trailer.ref.cmd \"~/bin/glog-grep\"\n $ git interpret-trailers --trailer=\"ref:Add copyright notices.\" and ","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:47Z","receivedAt":"2023-06-15T02:54:10Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nWe already use angle brackets elsewhere, so this makes things more\nconsistent.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 7516593c470..97dc1c8c95d 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -66,9 +66,9 @@ non-whitespace lines before a line that starts with '---' (followed by a\n space or the end of the line).\n \n When reading trailers, there can be no whitespace before or inside the\n-token, but any number of regular space and tab characters are allowed\n-between the token and the separator. There can be whitespaces before,\n-inside or after the value. The value may be split over multiple lines\n+, but any number of regular space and tab characters are allowed\n+between the and the separator. There can be whitespaces before,\n+inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n the \"folding\" in RFC 822.\n \n@@ -241,7 +241,7 @@ trailer..command::\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n-\tvalue that would be passed as argument.\n+\t that would be passed as argument.\n +\n The 'trailer..command' option has been deprecated in favor of\n 'trailer..cmd' due to the fact that $ARG in the user's command is\n-- \ngitgitgadget\n\n"},{"id":"478416","messageId":"f67458a366006763cc2fc9efa2dc5591732a323f.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 7/9] doc: trailer..command: emphasize deprecation","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:48Z","receivedAt":"2023-06-15T02:54:12Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThis puts the deprecation notice up front, instead of leaving it to the\nnext paragraph.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 97dc1c8c95d..6016af5c203 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -238,13 +238,13 @@ trailer..ifmissing::\n \tthat option for trailers with the specified .\n \n trailer..command::\n+\tDeprecated in favor of 'trailer..cmd'.\n \tThis option behaves in the same way as 'trailer..cmd', except\n \tthat it doesn't pass anything as argument to the specified command.\n \tInstead the first occurrence of substring $ARG is replaced by the\n \t that would be passed as argument.\n +\n-The 'trailer..command' option has been deprecated in favor of\n-'trailer..cmd' due to the fact that $ARG in the user's command is\n+Note that $ARG in the user's command is\n only replaced once and that the original way of replacing $ARG is not safe.\n +\n When both 'trailer..cmd' and 'trailer..command' are given\n-- \ngitgitgadget\n\n"},{"id":"478417","messageId":"604265c54dff9b2f16b8bf3b1964cae6280b756c.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 8/9] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:49Z","receivedAt":"2023-06-15T02:54:13Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nThe 'key' option is used frequently in the examples at the bottom but\nthere is no mention of it in the description.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 6016af5c203..7e77cbb1cad 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -49,7 +49,10 @@ token: value\n ------------------------------------------------\n \n This means that the trimmed and will be separated by\n-`': '` (one colon followed by one space).\n+`': '` (one colon followed by one space). For convenience, the can be a\n+shortened string key (e.g., \"sign\") instead of the full string which should\n+appear before the separator on the output (e.g., \"Signed-off-by\"). This can be\n+configured using the 'trailer..key' configuration variable.\n \n By default the new trailer will appear at the end of all the existing\n trailers. If there is no existing trailer, the new trailer will appear\n-- \ngitgitgadget\n\n"},{"id":"478418","messageId":"1a3755eacbe13fda2896659e115ff0692fe29cf6.1686797630.git.gitgitgadget@gmail.com","threadId":"59712","inReplyTo":"pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com","subject":"[PATCH v4 9/9] doc: trailer: add more examples in DESCRIPTION","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-06-15T02:53:50Z","receivedAt":"2023-06-15T02:54:21Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver \n\nBe more up-front about what trailers are in practice with examples, to\ngive the reader a visual cue while they go on to read the rest of the\ndescription.\n\nAlso add an example for multiline values.\n\nSigned-off-by: Linus Arver \n---\n Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--\n 1 file changed, 18 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex 7e77cbb1cad..55d89614661 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -16,7 +16,18 @@ DESCRIPTION\n -----------\n Add or parse 'trailer' lines that look similar to RFC 822 e-mail\n headers, at the end of the otherwise free-form part of a commit\n-message.\n+message. For example, in the following commit message\n+\n+------------------------------------------------\n+subject\n+\n+Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n+\n+Signed-off-by: Alice \n+Signed-off-by: Bob \n+------------------------------------------------\n+\n+the last two lines starting with \"Signed-off-by\" are trailers.\n \n This command reads commit messages from either the\n arguments or the standard input if no is specified.\n@@ -73,7 +84,12 @@ When reading trailers, there can be no whitespace before or inside the\n between the and the separator. There can be whitespaces before,\n inside or after the . The may be split over multiple lines\n with each subsequent line starting with at least one whitespace, like\n-the \"folding\" in RFC 822.\n+the \"folding\" in RFC 822. Example:\n+\n+------------------------------------------------\n+token: This is a very long value, with spaces and\n+ newlines in it.\n+------------------------------------------------\n \n Note that trailers do not follow (nor are they intended to follow) many of the\n rules for RFC 822 headers. For example they do not follow the encoding rule.\n-- \ngitgitgadget\n"},{"id":"478419","messageId":"owlyleglo2ji.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"CAP8UFD2iej1EhUtR=+wqcnnoYrwCPFoR2ed71Wswyd8CYPthFA@mail.gmail.com","subject":"Re: [PATCH v3 3/9] doc: trailer: drop \"commit message part\" phrasing","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-06-15T02:57:37Z","receivedAt":"2023-06-15T02:57:42Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Christian Couder writes:\n\n>> +This command can also operate on the output of \n>> linkgit:git-format-patch[1],\n>> +which is more elaborate than a plain commit message. Namely, such output\n>> +includes a commit message (as above), a \"---\" divider line, and a patch \n>> part.\n>> +For these inputs, the divider and patch parts are ignored, unless \n>> `--no-divider`\n>> +is specified.\n\n> I think saying \"the divider and patch parts are ignored\" is a bit\n> ambiguous. It could mean that when a patch is read by the command only\n> its commit message, possibly modified by the command, is emitted on\n> the standard output.\n\nIndeed. Updated in v4.\n"},{"id":"478420","messageId":"owlyilbpo2ad.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"CAP8UFD30qxHdyeOKXOuP7cE-9VB4f2mLWB2DLZz2Vskwt4QBDw@mail.gmail.com","subject":"Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word \"message\" by itself","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-06-15T03:03:06Z","receivedAt":"2023-06-15T03:03:20Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Christian Couder writes:\n\n>> $ git config trailer.sign.key \"Signed-off-by\"\n>> $ cat msg.txt\n>> subject\n\n>> -message\n>> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\n> I am not sure this change is clarifying anything. If you want\n> something clearer for \"internal body text inside the commit message\",\n> you could perhaps just use \"body\" or \"body text\".\n\n> I am not against using such latin words, but then why only in the body\n> and not in the subject too? And if it's used in the subject too, then\n> I am not sure it will make it easy for users to understand that the\n> example is using a simple commit message.\n\nI can't remember why I didn't just use \"body text\", which I agree is\nbetter than the (albeit famous) Latin phrase. It's shorter, simpler, and\nalso search-friendly (for cases where the user is not sure of exactly\nwhich word they want to search for). Updated in v4 to use \"body\ntext\".\n"},{"id":"478421","messageId":"owlyfs6to27m.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"CAP8UFD3ikE8k7TJnX7wOt9K3JAhkh4chB3Gjp1B2tofU81xXWg@mail.gmail.com","subject":"Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-06-15T03:04:45Z","receivedAt":"2023-06-15T03:05:01Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Christian Couder writes:\n\n>> This means that the trimmed and will be separated by\n>> -`': '` (one colon followed by one space).\n>> +`': '` (one colon followed by one space). If the should have a \n>> different\n>> +string representation than itself, then the 'key' can be configured with\n>> +'trailer..key'.\n\n> I would rather say something like:\n\n> \"A can be a shortcut name, for example \"sign\", instead of the\n> full string, for example \"Signed-off-by\", which should appear before\n> the separator on the output. This can be configured using the\n> 'trailer..key' configuration variable.\"\n\nUpdated in v4 with a slightly different wording versus your example.\n"},{"id":"478422","messageId":"owlycz1xo243.fsf@fine.c.googlers.com","threadId":"59712","inReplyTo":"CAP8UFD1uTFCMoh9SnxNpRkvAK=6_VLLo_7yH5tuqS2auyX5G4Q@mail.gmail.com","subject":"Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-06-15T03:06:52Z","receivedAt":"2023-06-15T03:06:57Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Christian Couder writes:\n\n> On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget\n> wrote:\n\n>> This series makes some small improvements to the docs for\n>> git-interpret-trailers. The intent is to make it easier to read for\n>> beginners who have never used this command before.\n\n> Thanks, and sorry for the late review. I found a few things that I\n> think could be improved, but I like the direction.\n\nNo worries. Thank you for your review comments!\n"},{"id":"478433","messageId":"CAP8UFD3ryDoewoKnSWQcXE2H7OFn6aqK-D6Gjav=qXFGmUnHLw@mail.gmail.com","threadId":"59712","inReplyTo":"owlycz1xo243.fsf@fine.c.googlers.com","subject":"Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2023-06-15T07:47:33Z","receivedAt":"2023-06-15T07:48:29Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Thu, Jun 15, 2023 at 5:06 AM Linus Arver wrote:\n>\n> Christian Couder writes:\n\n> > Thanks, and sorry for the late review. I found a few things that I\n> > think could be improved, but I like the direction.\n>\n> No worries. Thank you for your review comments!\n\nThe version 4 looks good to me now. Thanks!\n"}]}