| Message ID | pull.1506.v3.git.git.1686017304.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | docs: interpret-trailers: reword and add examples | expand |
On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget <gitgitgadget@gmail.com> wrote: > > 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. Thanks, and sorry for the late review. I found a few things that I think could be improved, but I like the direction.
Christian Couder <christian.couder@gmail.com> writes: > On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> 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. > Thanks, and sorry for the late review. I found a few things that I > think could be improved, but I like the direction. No worries. Thank you for your review comments!
On Thu, Jun 15, 2023 at 5:06 AM Linus Arver <linusa@google.com> wrote: > > Christian Couder <christian.couder@gmail.com> writes: > > Thanks, and sorry for the late review. I found a few things that I > > think could be improved, but I like the direction. > > No worries. Thank you for your review comments! The version 4 looks good to me now. Thanks!
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