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 v3 0/9] docs: interpret-trailers: reword and add examples
Date: Tue, 06 Jun 2023 02:08:15 +0000 [thread overview]
Message-ID: <pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1506.v2.git.git.1683839975.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 v2 to 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.
Changes from v1 to 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 | 132 +++++++++++++----------
1 file changed, 76 insertions(+), 56 deletions(-)
base-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v3
Pull-Request: https://github.com/git/git/pull/1506
Range-diff vs v2:
1: 65e6fbdec92 = 1: 7d504700b91 doc: trailer: fix grammar
2: 82353471831 = 2: 65386432ca4 doc: trailer: swap verb order
3: 5fabe166714 = 3: e0a56c8e61d doc: trailer: drop "commit message part" phrasing
4: 783a0b1e003 ! 4: 52f7d29f509 doc: trailer: examples: avoid the word "message" by itself
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
+ $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject
-message
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>
-@@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/glog-find-author"
- $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
- > subject
- >
--> message
-+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- >
- > EOF
+@@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
+ $ cat msg1.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+ $ 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 "$(git config user.name) <$(git config user.
+ $ git interpret-trailers --trailer sign <msg1.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ Signed-off-by: Bob <bob@example.com>
+ $ cat msg2.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ Signed-off-by: Alice <alice@example.com>
+ $ git interpret-trailers --trailer sign <msg2.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ Signed-off-by: Alice <alice@example.com>
+ ------------
+@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
+ $ cat msg.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+ $ git config trailer.help.key "Helped-by: "
+ $ git config trailer.help.ifExists "addIfDifferentNeighbor"
+ $ git config trailer.help.cmd "~/bin/glog-find-author"
+ $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject
-message
@@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/g
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>
-@@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/glog-grep"
- $ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
- > subject
- >
--> message
-+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- >
- > EOF
+@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
+ $ cat msg.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+ $ git config trailer.ref.key "Reference-to: "
+ $ git config trailer.ref.ifExists "replace"
+ $ git config trailer.ref.cmd "~/bin/glog-grep"
+ $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject
-message
@@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/gl
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
------------
-@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --ab
- $ git interpret-trailers <<EOF
- > subject
- >
--> message
-+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- >
- > see: HEAD~2
- > EOF
+@@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
+ $ cat msg.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ see: HEAD~2
+ $ cat ~/bin/glog-ref
+@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref"
+ $ git interpret-trailers --trailer=see <msg.txt
subject
-message
5: dd7e29fcc21 = 5: 4a2a0e41e4a doc: trailer: remove redundant phrasing
6: 96cb4ae2965 = 6: f99545409dc doc: trailer: use angle brackets for <token> and <value>
7: 4e234110ffd = 7: 6aba774489a doc: trailer.<token>.command: emphasize deprecation
8: 8aaf9e27d98 = 8: b13bd73d248 doc: trailer: mention 'key' in DESCRIPTION
9: 7e95198894b = 9: ec43e192d6e doc: trailer: add more examples in DESCRIPTION
--
gitgitgadget
next prev parent reply other threads:[~2023-06-06 2:08 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 ` Linus Arver via GitGitGadget [this message]
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.v3.git.git.1686017304.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 NNTP newsgroup(s).