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 v4 0/9] docs: interpret-trailers: reword and add examples
Date: Thu, 15 Jun 2023 02:53:41 +0000 [thread overview]
Message-ID: <pull.1506.v4.git.git.1686797630.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1506.v3.git.git.1686017304.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.
Updates in v4
=============
* vs Patch v3 3/9: Reworded a sentence to avoid ambiguity with the word
"ignored".
* vs Patch v3 4/9: Replaced "Lorem ipsum..." in favor of "body text" which
is shorter and more obvious (and search-friendly).
* vs Patch v3 8/9: Expanded the explanation about 'trailer..key' and its
convenience, instead of only stating how to use this option.
Updates in v3
=============
* Rebased on top of "master" at fe86abd751 (Git 2.41, 2023-06-01). The only
conflict was in Patch v2 4/9
(https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),
because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)
added the "subject/message" style for the examples that did not have any
message text in them. These examples' additional message lines have been
replaced with Lorem ipsum... like the others in Patch v2 4/9.
Updates in v2
=============
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 | 134 +++++++++++++----------
1 file changed, 78 insertions(+), 56 deletions(-)
base-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v4
Pull-Request: https://github.com/git/git/pull/1506
Range-diff vs v3:
1: 7d504700b91 = 1: 7d504700b91 doc: trailer: fix grammar
2: 65386432ca4 = 2: 65386432ca4 doc: trailer: swap verb order
3: e0a56c8e61d ! 3: 3c85477d791 doc: trailer: drop "commit message part" phrasing
@@ Documentation/git-interpret-trailers.txt: Add or parse 'trailer' lines that look
+This command can also operate on the output of linkgit:git-format-patch[1],
+which is more elaborate than a plain commit message. Namely, such output
+includes a commit message (as above), a "---" divider line, and a patch part.
-+For these inputs, the divider and patch parts are ignored, unless `--no-divider`
-+is specified.
++For these inputs, the divider and patch parts are not modified by
++this command and are emitted as is on the output, unless
++`--no-divider` is specified.
Some configuration variables control the way the `--trailer` arguments
-are applied to each commit message and the way any existing trailer in
4: 52f7d29f509 ! 4: 6b4cb31b170 doc: trailer: examples: avoid the word "message" by itself
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>
@@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
@@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo "$
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Signed-off-by: Alice <alice@example.com>
------------
@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>
@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
------------
@@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
see: HEAD~2
$ cat ~/bin/glog-ref
@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
++body text
See-also: fe3187489d69c4 (subject of related commit)
------------
5: 4a2a0e41e4a = 5: a4a2ed16dcc doc: trailer: remove redundant phrasing
6: f99545409dc = 6: 7a96d0705b9 doc: trailer: use angle brackets for <token> and <value>
7: 6aba774489a = 7: f67458a3660 doc: trailer.<token>.command: emphasize deprecation
8: b13bd73d248 ! 8: 604265c54df doc: trailer: mention 'key' in DESCRIPTION
@@ Documentation/git-interpret-trailers.txt: token: value
This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space).
-+`': '` (one colon followed by one space). If the <token> should have a different
-+string representation than itself, then the 'key' can be configured with
-+'trailer.<token>.key'.
++`': '` (one colon followed by one space). For convenience, the <token> can be a
++shortened string key (e.g., "sign") instead of the full string which should
++appear before the separator on the output (e.g., "Signed-off-by"). This can be
++configured using the 'trailer.<token>.key' configuration variable.
By default the new trailer will appear at the end of all the existing
trailers. If there is no existing trailer, the new trailer will appear
9: ec43e192d6e = 9: 1a3755eacbe doc: trailer: add more examples in DESCRIPTION
--
gitgitgadget
next prev parent reply other threads:[~2023-06-15 2:53 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 ` [PATCH v2 0/9] " Linus Arver via GitGitGadget
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 ` Linus Arver via GitGitGadget [this message]
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.v4.git.git.1686797630.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).