From: Linus Arver via GitGitGadget Date: Thu, 15 Jun 2023 02:53:41 GMT Subject: [PATCH v4 0/9] docs: interpret-trailers: reword and add examples Message-ID: In-Reply-To: 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..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 and doc: trailer..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 ' --trailer 'sign: Bob ' Signed-off-by: Bob @@ Documentation/git-interpret-trailers.txt: EXAMPLES subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Bob $ git interpret-trailers --trailer 'Acked-by: Alice ' --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 Acked-by: Alice @@ 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 $ cat msg2.txt subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Alice $ git interpret-trailers --trailer sign ------------ @@ 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 Helped-by: Christian Couder @@ 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 and 7: 6aba774489a = 7: f67458a3660 doc: trailer..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 and will be separated by -`': '` (one colon followed by one space). -+`': '` (one colon followed by one space). If the should have a different -+string representation than itself, then the 'key' can be configured with -+'trailer..key'. ++`': '` (one colon followed by one space). For convenience, the 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..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