mbox series

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

Message ID pull.1471.v4.git.git.1684469874.gitgitgadget@gmail.com (mailing list archive)
Headers show
Series Document the output format of ls-remote | expand

Message

Philippe Blain via GitGitGadget May 19, 2023, 4:17 a.m. UTC 
This iteration incorporates the feedback from v3. A capitalization
inconsistency was fixed and the 'peeled tag' / ^{} discussion in
git-ls-remote.txt was clarified.

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   | 48 +++++++++++++++++++++++--------
 Documentation/git-show-branch.txt | 16 +++++------
 Documentation/git-show-ref.txt    | 40 +++++++++++++++++---------
 3 files changed, 70 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-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v4
Pull-Request: https://github.com/git/git/pull/1471

Range-diff vs v3:

 1:  fe442c2041b ! 1:  49382e81e02 show-ref doc: update for internal consistency
     @@ Commit message
      
          - 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.
     +    - Use 'OID' (for 'object ID') instead of 'SHA-1' as we support
     +      different hashing algorithms these days.
      
          Signed-off-by: Sean Allred <allred.sean@gmail.com>
      
     @@ Documentation/git-show-ref.txt: $ git show-ref --head --dereference
      +When using `--hash` (and not `--dereference`), the output is in the format:
      +
      +------------
     -+<OID> LF
     ++<oid> LF
      +------------
      +
      +For example,
 2:  cd51a70f3ff = 2:  ea10e7964a9 show-branch doc: say <ref>, not <reference>
 3:  8b644fb1203 = 3:  cdd933e6fc3 ls-remote doc: remove redundant --tags example
 4:  dc0c5ba1751 = 4:  68c35f605ae ls-remote doc: show peeled tags in examples
 5:  94380984533 = 5:  cfb5dd0e87e ls-remote doc: explain what each example does
 6:  de57b8aa563 ! 6:  115dba15ce0 ls-remote doc: document the output format
     @@ Documentation/git-ls-remote.txt: OPTIONS
      +<oid> TAB <ref> LF
      +------------
      +
     -+When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
     -+representation.
     ++When showing an annotated tag, unless `--refs` is given, two such
     ++lines are shown: one with the refname for the tag itself as `<ref>`,
     ++and another with `<ref>` followed by `^{}`. The `<oid>` on the latter
     ++line shows the name of the object the tag points at.
      +
       EXAMPLES
       --------