From: "Sean Allred via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Eric Sunshine <sunshine@sunshineco.com>,
Sean Allred <allred.sean@gmail.com>,
Sean Allred <code@seanallred.com>
Subject: [PATCH v3 0/6] Document the output format of ls-remote
Date: Mon, 15 May 2023 12:13:07 +0000 [thread overview]
Message-ID: <pull.1471.v3.git.git.1684152793.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1471.v2.git.git.1679478573.gitgitgadget@gmail.com>
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@gmail.com>
## 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@gmail.com>
@@ 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@gmail.com>
## 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@gmail.com>
## 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
next prev parent reply other threads:[~2023-05-15 12:13 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-18 15:33 [PATCH] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-03-19 17:30 ` Eric Sunshine
2023-03-19 19:25 ` Felipe Contreras
2023-03-19 21:36 ` Sean Allred
2023-03-22 9:49 ` [PATCH v2 0/2] " Sean Allred via GitGitGadget
2023-03-22 9:49 ` [PATCH v2 1/2] Update show-ref documentation for internal consistency Sean Allred via GitGitGadget
2023-03-22 16:50 ` Junio C Hamano
2023-03-22 9:49 ` [PATCH v2 2/2] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-03-22 16:48 ` Junio C Hamano
2023-03-22 17:13 ` Re* " Junio C Hamano
2023-05-15 12:13 ` Sean Allred via GitGitGadget [this message]
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-15 16:58 ` Eric Sunshine
2023-05-15 17:27 ` Junio C Hamano
2023-05-19 3:51 ` Sean Allred
2023-05-15 19:48 ` Junio C Hamano
2023-05-19 3:55 ` Sean Allred
2023-05-15 12:13 ` [PATCH v3 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
2023-05-15 19:52 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
2023-05-15 19:53 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
2023-05-15 20:01 ` Junio C Hamano
2023-05-19 4:04 ` Sean Allred
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=pull.1471.v3.git.git.1684152793.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=allred.sean@gmail.com \
--cc=code@seanallred.com \
--cc=git@vger.kernel.org \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).