Document the output format of ls-remote

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.

@@ 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
--------

gitgitgadget