Git Mailing List Archive mirror
 help / color / mirror / code / Atom feed
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>,
	Sean Allred <allred.sean@gmail.com>
Subject: [PATCH v4 1/6] show-ref doc: update for internal consistency
Date: Fri, 19 May 2023 04:17:49 +0000	[thread overview]
Message-ID: <49382e81e02c4da2460eb35978044b6ed2e3049a.1684469874.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1471.v4.git.git.1684469874.gitgitgadget@gmail.com>

From: Sean Allred <allred.sean@gmail.com>

- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.
- 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 | 40 ++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index d1d56f68b43..44c7387d78f 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -23,7 +23,7 @@ particular ref exists.
 
 By default, shows the tags, heads, and remote refs.
 
-The --exclude-existing form is a filter that does the inverse. It reads
+The `--exclude-existing` form is a filter that does the inverse. It reads
 refs from stdin, one ref per line, and shows those that don't exist in
 the local repository.
 
@@ -47,14 +47,14 @@ OPTIONS
 -d::
 --dereference::
 
-	Dereference tags into object IDs as well. They will be shown with "{caret}{}"
+	Dereference tags into object IDs as well. They will be shown with `{caret}{}`
 	appended.
 
 -s::
 --hash[=<n>]::
 
-	Only show the SHA-1 hash, not the reference name. When combined with
-	--dereference the dereferenced tag will still be shown after the SHA-1.
+	Only show the OID, not the reference name. When combined with
+	`--dereference`, the dereferenced tag will still be shown after the OID.
 
 --verify::
 
@@ -70,15 +70,15 @@ OPTIONS
 -q::
 --quiet::
 
-	Do not print any results to stdout. When combined with `--verify` this
+	Do not print any results to stdout. When combined with `--verify`, this
 	can be used to silently check if a reference exists.
 
 --exclude-existing[=<pattern>]::
 
-	Make 'git show-ref' act as a filter that reads refs from stdin of the
-	form "`^(?:<anything>\s)?<refname>(?:\^{})?$`"
+	Make `git show-ref` act as a filter that reads refs from stdin of the
+	form `^(?:<anything>\s)?<refname>(?:\^{})?$`
 	and performs the following actions on each:
-	(1) strip "{caret}{}" at the end of line if any;
+	(1) strip `{caret}{}` at the end of line if any;
 	(2) ignore if pattern is provided and does not head-match refname;
 	(3) warn if refname is not a well-formed refname and skip;
 	(4) ignore if refname is a ref that exists in the local repository;
@@ -96,7 +96,13 @@ OPTIONS
 OUTPUT
 ------
 
-The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
+The output is in the format:
+
+------------
+<oid> SP <ref> LF
+------------
+
+For example,
 
 -----------------------------------------------------------------------------
 $ git show-ref --head --dereference
@@ -110,7 +116,13 @@ $ git show-ref --head --dereference
 ...
 -----------------------------------------------------------------------------
 
-When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
+When using `--hash` (and not `--dereference`), the output is in the format:
+
+------------
+<oid> LF
+------------
+
+For example,
 
 -----------------------------------------------------------------------------
 $ git show-ref --heads --hash
@@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path:
 
 will only match the exact branch called "master".
 
-If nothing matches, 'git show-ref' will return an error code of 1,
+If nothing matches, `git show-ref` will return an error code of 1,
 and in the case of verification, it will show an error message.
 
-For scripting, you can ask it to be quiet with the "--quiet" flag, which
+For scripting, you can ask it to be quiet with the `--quiet` flag, which
 allows you to do things like
 
 -----------------------------------------------------------------------------
@@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't
 actually want to show any results, and we want to use the full refname for it
 in order to not trigger the problem with ambiguous partial matches).
 
-To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
+To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
 respectively (using both means that it shows tags and heads, but not other
 random references under the refs/ subdirectory).
 
-To do automatic tag object dereferencing, use the "-d" or "--dereference"
+To do automatic tag object dereferencing, use the `-d` or `--dereference`
 flag, so you can do
 
 -----------------------------------------------------------------------------
-- 
gitgitgadget


  reply	other threads:[~2023-05-19  4:18 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   ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
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       ` Sean Allred via GitGitGadget [this message]
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=49382e81e02c4da2460eb35978044b6ed2e3049a.1684469874.git.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.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/pub/scm/git/git.git/

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).