[v3,0/6] Document the output format of ls-remote

Message

Philippe Blain via GitGitGadget May 15, 2023, 12:13 p.m. UTC

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 <[e-mail]>
      
       ## 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 <[e-mail]>
      
     @@ 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 <[e-mail]>
      
       ## 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 <[e-mail]>
      
       ## 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
      [phone]c68591989456e3ba0a5442f93152c1a	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:
     + +
     + ----