show-ref doc: update for internal consistency
- 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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sean Allred committed
May 19, 2023 at 04:17 UTC
00bf685975d7a4a163d8a57d1a666ae6642c6441
1 file changed
+26
-14
Documentation/git-show-ref.txt
+26
-14
@@ -23,7 +23,7 @@ particular ref exists.
23
24
By default, shows the tags, heads, and remote refs.
25
26
-The --exclude-existing form is a filter that does the inverse. It reads
26
+The `--exclude-existing` form is a filter that does the inverse. It reads
27
refs from stdin, one ref per line, and shows those that don't exist in
28
the local repository.
29
@@ -47,14 +47,14 @@ OPTIONS
47
-d::
48
--dereference::
49
50
- Dereference tags into object IDs as well. They will be shown with "{caret}{}"
50
+ Dereference tags into object IDs as well. They will be shown with `{caret}{}`
51
appended.
52
53
-s::
54
--hash[=<n>]::
55
56
- Only show the SHA-1 hash, not the reference name. When combined with
57
- --dereference the dereferenced tag will still be shown after the SHA-1.
56
+ Only show the OID, not the reference name. When combined with
57
+ `--dereference`, the dereferenced tag will still be shown after the OID.
58
59
--verify::
60
@@ -70,15 +70,15 @@ OPTIONS
70
-q::
71
--quiet::
72
73
- Do not print any results to stdout. When combined with `--verify` this
73
+ Do not print any results to stdout. When combined with `--verify`, this
74
can be used to silently check if a reference exists.
75
76
--exclude-existing[=<pattern>]::
77
78
- Make 'git show-ref' act as a filter that reads refs from stdin of the
79
- form "`^(?:<anything>\s)?<refname>(?:\^{})?$`"
78
+ Make `git show-ref` act as a filter that reads refs from stdin of the
79
+ form `^(?:<anything>\s)?<refname>(?:\^{})?$`
80
and performs the following actions on each:
81
- (1) strip "{caret}{}" at the end of line if any;
81
+ (1) strip `{caret}{}` at the end of line if any;
82
(2) ignore if pattern is provided and does not head-match refname;
83
(3) warn if refname is not a well-formed refname and skip;
84
(4) ignore if refname is a ref that exists in the local repository;
@@ -96,7 +96,13 @@ OPTIONS
96
OUTPUT
97
------
98
99
-The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
99
+The output is in the format:
100
+
101
+------------
102
+<oid> SP <ref> LF
103
+------------
104
+
105
+For example,
106
107
-----------------------------------------------------------------------------
108
$ git show-ref --head --dereference
@@ -110,7 +116,13 @@ $ git show-ref --head --dereference
116
...
117
-----------------------------------------------------------------------------
118
113
-When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
119
+When using `--hash` (and not `--dereference`), the output is in the format:
120
+
121
+------------
122
+<oid> LF
123
+------------
124
+
125
+For example,
126
127
-----------------------------------------------------------------------------
128
$ git show-ref --heads --hash
@@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path:
154
155
will only match the exact branch called "master".
156
145
-If nothing matches, 'git show-ref' will return an error code of 1,
157
+If nothing matches, `git show-ref` will return an error code of 1,
158
and in the case of verification, it will show an error message.
159
148
-For scripting, you can ask it to be quiet with the "--quiet" flag, which
160
+For scripting, you can ask it to be quiet with the `--quiet` flag, which
161
allows you to do things like
162
163
-----------------------------------------------------------------------------
@@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't
169
actually want to show any results, and we want to use the full refname for it
170
in order to not trigger the problem with ambiguous partial matches).
171
160
-To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
172
+To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
173
respectively (using both means that it shows tags and heads, but not other
174
random references under the refs/ subdirectory).
175
164
-To do automatic tag object dereferencing, use the "-d" or "--dereference"
176
+To do automatic tag object dereferencing, use the `-d` or `--dereference`
177
flag, so you can do
178
179
-----------------------------------------------------------------------------