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@xxxxxxxxx/), 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@xxxxxxxxxxx>' --trailer 'sign: Bob <bob@xxxxxxxxxxx>' <msg.txt subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Alice <alice@xxxxxxxxxxx> Signed-off-by: Bob <bob@xxxxxxxxxxx> @@ Documentation/git-interpret-trailers.txt: EXAMPLES subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Bob <bob@xxxxxxxxxxx> $ git interpret-trailers --trailer 'Acked-by: Alice <alice@xxxxxxxxxxx>' --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@xxxxxxxxxxx> Acked-by: Alice <alice@xxxxxxxxxxx> @@ 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@xxxxxxxxxxx> $ cat msg2.txt subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Alice <alice@xxxxxxxxxxx> $ git interpret-trailers --trailer sign <msg2.txt subject -message -+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text Signed-off-by: Alice <alice@xxxxxxxxxxx> ------------ @@ 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@xxxxxxxxx> Helped-by: Christian Couder <christian.couder@xxxxxxxxx> @@ 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
