This iteration incorporates the feedback from v2 with additional patches to explain examples and remove redundant ones. These patches are of course explained in the commit messages, but they're in response to actual conversation [https://github.com/git/git/pull/1471#issuecomment-1547726140] that I cannot seem to actually respond to for unknown technical reasons. A bit off-topic: for the past few months, I have been having some serious trouble interacting with this list via the usual means [https://github.com/git/git/pull/1471#issuecomment-1547726140] and would appreciate anyone may be able to diagnose the issue. I will be reaching out to the site/list owners as a first step (having exhausted my own investigation, of course). If you have any ideas, please feel free to email me directly / off-list or leave a comment on GitHub if you are so inclined -- I of course don't want this to become a support thread. I'd much rather keep conversation here to the topic of getting these patches merged :-) Junio C Hamano (1): show-branch doc: say <ref>, not <reference> Sean Allred (5): show-ref doc: update for internal consistency ls-remote doc: remove redundant --tags example ls-remote doc: show peeled tags in examples ls-remote doc: explain what each example does ls-remote doc: document the output format Documentation/git-ls-remote.txt | 46 +++++++++++++++++++++++-------- Documentation/git-show-branch.txt | 16 +++++------ Documentation/git-show-ref.txt | 40 +++++++++++++++++---------- 3 files changed, 68 insertions(+), 34 deletions(-) base-commit: 950264636c68591989456e3ba0a5442f93152c1a Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v3 Pull-Request: https://github.com/git/git/pull/1471 Range-diff vs v2: 1: 4408b518810 ! 1: fe442c2041b Update show-ref documentation for internal consistency @@ Metadata Author: Sean Allred <allred.sean@xxxxxxxxx> ## Commit message ## - Update show-ref documentation for internal consistency + show-ref doc: update for internal consistency - Use inline-code syntax for options where appropriate. - Use code blocks to clarify output format. - This patch also swaps out 'SHA-1' language for the - implementation-agnostic 'OID' term where appropriate in preparation for - supporting different hashing algorithms. + This patch also swaps out 'SHA-1' language for the implementation- + agnostic 'OID' term where appropriate in preparation for supporting + different hashing algorithms. Signed-off-by: Sean Allred <allred.sean@xxxxxxxxx> @@ Documentation/git-show-ref.txt: OPTIONS +The output is in the format: + +------------ -+<OID> SP <reference name> LF ++<oid> SP <ref> LF +------------ + +For example, -: ----------- > 2: cd51a70f3ff show-branch doc: say <ref>, not <reference> -: ----------- > 3: 8b644fb1203 ls-remote doc: remove redundant --tags example -: ----------- > 4: dc0c5ba1751 ls-remote doc: show peeled tags in examples -: ----------- > 5: 94380984533 ls-remote doc: explain what each example does 2: 44e79f0d69c ! 6: de57b8aa563 Document the output format of ls-remote @@ Metadata Author: Sean Allred <allred.sean@xxxxxxxxx> ## Commit message ## - Document the output format of ls-remote + ls-remote doc: document the output format While well-established, the output format of ls-remote was not actually documented. This patch adds an OUTPUT section to the documentation following the format of git-show-ref.txt (which has similar semantics). + Add a basic example immediately after this to solidify the 'normal' + output format. + Signed-off-by: Sean Allred <allred.sean@xxxxxxxxx> ## Documentation/git-ls-remote.txt ## @@ Documentation/git-ls-remote.txt: OPTIONS +The output is in the format: + +------------ -+<OID> TAB <reference name> LF ++<oid> TAB <ref> LF +------------ + -+For example, ++When `<ref>` is a tag, it may be followed by `^{}` to show its peeled ++representation. + + EXAMPLES + -------- + ++* List all references (including symbolics and pseudorefs), peeling ++ tags: +++ +---- +$ git ls-remote ++27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main -+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/heads/maint +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next -+74a0ffe000da036ce4ca843d991a7c6b8c246a08 refs/heads/seen -+860bc4360c4fcba0fe2df942984d87f8467af3df refs/heads/todo +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 -+8810a79228a149a9773bf9c75f381fca27a6a80e refs/tags/v2.40.0-rc0 -+f899c182d0bffb6e915da7c8db9be202b144c098 refs/tags/v2.40.0-rc1 -+6bed3304b2b2f1cf440ca3050b57a7cf3a3fe687 refs/tags/v2.40.0-rc2 ++73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} +---- + - EXAMPLES - -------- - + * List all references matching given patterns: + + + ---- -- gitgitgadget
