From: "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Junio C Hamano <gitster@pobox.com>,
Christian Couder <christian.couder@gmail.com>,
Linus Arver <linusa@google.com>
Subject: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples
Date: Thu, 11 May 2023 21:19:26 +0000 [thread overview]
Message-ID: <pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1506.git.git.1683566870.gitgitgadget@gmail.com>
This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.
Changes from v1
===============
In order of significance:
* The phrase "commit message part" has been removed.
* The word "message" is always used as part of the bigger phrase "commit
message".
* Deprecation language for trailer.<token>.command has been updated to
minimize whitespace churn, while also tweaking the 2nd paragraph to
reduce duplication.
* The phrase "Lorem ipsum..." is always only used to stand in for the body
paragraph(s) of a commit message.
* Grammar fixes have been squashed together (01+06 previously).
Linus Arver (9):
doc: trailer: fix grammar
doc: trailer: swap verb order
doc: trailer: drop "commit message part" phrasing
doc: trailer: examples: avoid the word "message" by itself
doc: trailer: remove redundant phrasing
doc: trailer: use angle brackets for <token> and <value>
doc: trailer.<token>.command: emphasize deprecation
doc: trailer: mention 'key' in DESCRIPTION
doc: trailer: add more examples in DESCRIPTION
Documentation/git-interpret-trailers.txt | 124 +++++++++++++----------
1 file changed, 72 insertions(+), 52 deletions(-)
base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v2
Pull-Request: https://github.com/git/git/pull/1506
Range-diff vs v1:
1: 12d4850a9ab ! 1: 65e6fbdec92 doc: trailer: fix grammar
@@ Documentation/git-interpret-trailers.txt: SYNOPSIS
DESCRIPTION
-----------
-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
-+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
++Parse or add 'trailer' lines that look similar to RFC 822 e-mail
headers, at the end of the otherwise free-form part of a commit
message.
+@@ Documentation/git-interpret-trailers.txt: for the same <token>, 'trailer.<token>.cmd' is used and
+ 'trailer.<token>.command' is ignored.
+
+ trailer.<token>.cmd::
+- This option can be used to specify a shell command that will be called:
++ This option can be used to specify a shell command that will be called
+ once to automatically add a trailer with the specified <token>, and then
+- each time a '--trailer <token>=<value>' argument to modify the <value> of
+- the trailer that this option would produce.
++ called each time a '--trailer <token>=<value>' argument is specified to
++ modify the <value> of the trailer that this option would produce.
+ +
+ When the specified command is first called to add a trailer
+ with the specified <token>, the behavior is as if a special
2: b7717424437 ! 2: 82353471831 doc: trailer: swap verb order
@@ Documentation/git-interpret-trailers.txt: SYNOPSIS
DESCRIPTION
-----------
--Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
-+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
+-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
++Add or parse 'trailer' lines that look similar to RFC 822 e-mail
headers, at the end of the otherwise free-form part of a commit
message.
3: ad2d669eb0a < -: ----------- doc: trailer: --no-divider: more precise language
4: 0c10e40794d < -: ----------- doc: trailer: explain "commit mesage part" on first usage
-: ----------- > 3: 5fabe166714 doc: trailer: drop "commit message part" phrasing
-: ----------- > 4: 783a0b1e003 doc: trailer: examples: avoid the word "message" by itself
5: 5bad365c786 = 5: dd7e29fcc21 doc: trailer: remove redundant phrasing
6: 8e36d1bd1f0 < -: ----------- doc: trailer: trailer.<token>.cmd: add missing verb phrase
7: ab11527ca58 ! 6: 96cb4ae2965 doc: trailer: use angle brackets for <token> and <value>
@@ Commit message
Signed-off-by: Linus Arver <linusa@google.com>
## Documentation/git-interpret-trailers.txt ##
-@@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such three minus signs start the patch
- part of the message. See also `--no-divider` below.
+@@ Documentation/git-interpret-trailers.txt: non-whitespace lines before a line that starts with '---' (followed by a
+ space or the end of the line).
When reading trailers, there can be no whitespace before or inside the
-token, but any number of regular space and tab characters are allowed
@@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such th
with each subsequent line starting with at least one whitespace, like
the "folding" in RFC 822.
+@@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
+ This option behaves in the same way as 'trailer.<token>.cmd', except
+ that it doesn't pass anything as argument to the specified command.
+ Instead the first occurrence of substring $ARG is replaced by the
+- value that would be passed as argument.
++ <value> that would be passed as argument.
+ +
+ The 'trailer.<token>.command' option has been deprecated in favor of
+ 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
8: 59804321793 ! 7: 4e234110ffd doc: trailer.<token>.command: refer to existing example
@@ Metadata
Author: Linus Arver <linusa@google.com>
## Commit message ##
- doc: trailer.<token>.command: refer to existing example
+ doc: trailer.<token>.command: emphasize deprecation
+
+ This puts the deprecation notice up front, instead of leaving it to the
+ next paragraph.
Signed-off-by: Linus Arver <linusa@google.com>
@@ Documentation/git-interpret-trailers.txt: trailer.<token>.ifmissing::
that option for trailers with the specified <token>.
trailer.<token>.command::
-- This option behaves in the same way as 'trailer.<token>.cmd', except
-- that it doesn't pass anything as argument to the specified command.
-- Instead the first occurrence of substring $ARG is replaced by the
-- value that would be passed as argument.
-+ This option behaves in the
-+ same way as 'trailer.<token>.cmd', except that it doesn't pass anything as
-+ argument to the specified command. Instead the first occurrence of substring
-+ $ARG is replaced by the <value> from the trailer. See the
-+ 'trailer.see.command' trailer example in the "EXAMPLES" section below.
++ Deprecated in favor of 'trailer.<token>.cmd'.
+ This option behaves in the same way as 'trailer.<token>.cmd', except
+ that it doesn't pass anything as argument to the specified command.
+ Instead the first occurrence of substring $ARG is replaced by the
+ <value> that would be passed as argument.
+ +
+-The 'trailer.<token>.command' option has been deprecated in favor of
+-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
++Note that $ARG in the user's command is
+ only replaced once and that the original way of replacing $ARG is not safe.
+
- The 'trailer.<token>.command' option has been deprecated in favor of
- 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
+ When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
9: 1ac58b0b07c < -: ----------- doc: trailer.<token>.command: emphasize deprecation
10: 2c04a5ba7f0 = 8: 8aaf9e27d98 doc: trailer: mention 'key' in DESCRIPTION
11: ea483b364b4 ! 9: 7e95198894b doc: trailer: add more examples in DESCRIPTION
@@ Commit message
## Documentation/git-interpret-trailers.txt ##
@@ Documentation/git-interpret-trailers.txt: DESCRIPTION
-----------
- Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
+ Add or parse 'trailer' lines that look similar to RFC 822 e-mail
headers, at the end of the otherwise free-form part of a commit
-message.
+message. For example, in the following commit message
@@ Documentation/git-interpret-trailers.txt: DESCRIPTION
+------------------------------------------------
+subject
+
-+message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
@@ Documentation/git-interpret-trailers.txt: DESCRIPTION
+
+the last two lines starting with "Signed-off-by" are trailers.
- This command reads some patches or commit messages from either the
- <file> arguments or the standard input if no <file> is specified. If
+ This command reads commit messages from either the
+ <file> arguments or the standard input if no <file> is specified.
@@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no whitespace before or inside the
between the <token> and the separator. There can be whitespaces before,
inside or after the <value>. The <value> may be split over multiple lines
@@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no
+the "folding" in RFC 822. Example:
+
+------------------------------------------------
-+token: Lorem ipsum dolor sit amet, consectetur
-+ adipiscing elit.
++token: This is a very long value, with spaces and
++ newlines in it.
+------------------------------------------------
Note that trailers do not follow (nor are they intended to follow) many of the
--
gitgitgadget
next prev parent reply other threads:[~2023-05-11 21:19 UTC|newest]
Thread overview: 73+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-05-08 17:27 [PATCH 00/11] docs: interpret-trailers: reword and add examples Linus Arver via GitGitGadget
2023-05-08 17:27 ` [PATCH 01/11] doc: trailer: fix grammar Linus Arver via GitGitGadget
2023-05-08 19:19 ` Junio C Hamano
2023-05-08 19:33 ` Linus Arver
2023-05-08 21:35 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 02/11] doc: trailer: swap verb order Linus Arver via GitGitGadget
2023-05-08 19:20 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 03/11] doc: trailer: --no-divider: more precise language Linus Arver via GitGitGadget
2023-05-08 19:32 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage Linus Arver via GitGitGadget
2023-05-08 19:37 ` Junio C Hamano
2023-05-10 6:44 ` Linus Arver
2023-05-08 17:27 ` [PATCH 05/11] doc: trailer: remove redundant phrasing Linus Arver via GitGitGadget
2023-05-08 17:27 ` [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase Linus Arver via GitGitGadget
2023-05-08 19:41 ` Junio C Hamano
2023-05-10 6:52 ` Linus Arver
2023-05-10 16:37 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 07/11] doc: trailer: use angle brackets for <token> and <value> Linus Arver via GitGitGadget
2023-05-08 19:38 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 08/11] doc: trailer.<token>.command: refer to existing example Linus Arver via GitGitGadget
2023-05-08 19:47 ` Junio C Hamano
2023-05-10 7:08 ` Linus Arver
2023-05-10 16:42 ` Junio C Hamano
2023-05-08 17:27 ` [PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation Linus Arver via GitGitGadget
2023-05-08 19:48 ` Junio C Hamano
2023-05-10 7:10 ` Linus Arver
2023-05-08 17:27 ` [PATCH 10/11] doc: trailer: mention 'key' in DESCRIPTION Linus Arver via GitGitGadget
2023-05-08 17:27 ` [PATCH 11/11] doc: trailer: add more examples " Linus Arver via GitGitGadget
2023-05-08 19:50 ` Junio C Hamano
2023-05-08 17:49 ` [PATCH 00/11] docs: interpret-trailers: reword and add examples Junio C Hamano
2023-05-08 19:07 ` Linus Arver
2023-05-11 21:19 ` Linus Arver via GitGitGadget [this message]
2023-05-11 21:19 ` [PATCH v2 1/9] doc: trailer: fix grammar Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 2/9] doc: trailer: swap verb order Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 3/9] doc: trailer: drop "commit message part" phrasing Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 4/9] doc: trailer: examples: avoid the word "message" by itself Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 5/9] doc: trailer: remove redundant phrasing Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 6/9] doc: trailer: use angle brackets for <token> and <value> Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 7/9] doc: trailer.<token>.command: emphasize deprecation Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 8/9] doc: trailer: mention 'key' in DESCRIPTION Linus Arver via GitGitGadget
2023-05-11 21:19 ` [PATCH v2 9/9] doc: trailer: add more examples " Linus Arver via GitGitGadget
2023-05-12 23:24 ` [PATCH v2 0/9] docs: interpret-trailers: reword and add examples Junio C Hamano
2023-05-16 22:57 ` Linus Arver
2023-05-16 23:18 ` Junio C Hamano
2023-06-06 2:08 ` [PATCH v3 " Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 1/9] doc: trailer: fix grammar Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 2/9] doc: trailer: swap verb order Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing Linus Arver via GitGitGadget
2023-06-14 15:00 ` Christian Couder
2023-06-15 2:57 ` Linus Arver
2023-06-06 2:08 ` [PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself Linus Arver via GitGitGadget
2023-06-14 15:12 ` Christian Couder
2023-06-15 3:03 ` Linus Arver
2023-06-06 2:08 ` [PATCH v3 5/9] doc: trailer: remove redundant phrasing Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 6/9] doc: trailer: use angle brackets for <token> and <value> Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 7/9] doc: trailer.<token>.command: emphasize deprecation Linus Arver via GitGitGadget
2023-06-06 2:08 ` [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION Linus Arver via GitGitGadget
2023-06-14 15:27 ` Christian Couder
2023-06-15 3:04 ` Linus Arver
2023-06-06 2:08 ` [PATCH v3 9/9] doc: trailer: add more examples " Linus Arver via GitGitGadget
2023-06-14 15:36 ` [PATCH v3 0/9] docs: interpret-trailers: reword and add examples Christian Couder
2023-06-15 3:06 ` Linus Arver
2023-06-15 7:47 ` Christian Couder
2023-06-15 2:53 ` [PATCH v4 " Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 1/9] doc: trailer: fix grammar Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 2/9] doc: trailer: swap verb order Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 3/9] doc: trailer: drop "commit message part" phrasing Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 4/9] doc: trailer: examples: avoid the word "message" by itself Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 5/9] doc: trailer: remove redundant phrasing Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 6/9] doc: trailer: use angle brackets for <token> and <value> Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 7/9] doc: trailer.<token>.command: emphasize deprecation Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 8/9] doc: trailer: mention 'key' in DESCRIPTION Linus Arver via GitGitGadget
2023-06-15 2:53 ` [PATCH v4 9/9] doc: trailer: add more examples " Linus Arver via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=pull.1506.v2.git.git.1683839975.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=christian.couder@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=linusa@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).