]>
Commit | Line | Data |
---|---|---|
c0990ff3 JF |
1 | git-show-ref(1) |
2 | =============== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-show-ref - List references in a local repository | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
1307d5e8 | 11 | 'git show-ref' [--head] [-d | --dereference] |
e2f4e7e8 | 12 | [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] |
4318d3ba | 13 | [--heads] [--] [<pattern>...] |
1307d5e8 PS |
14 | 'git show-ref' --verify [-q | --quiet] [-d | --dereference] |
15 | [-s | --hash[=<n>]] [--abbrev[=<n>]] | |
16 | [--] [<ref>...] | |
33e8fc87 | 17 | 'git show-ref' --exclude-existing[=<pattern>] |
9080a7f1 | 18 | 'git show-ref' --exists <ref> |
c0990ff3 JF |
19 | |
20 | DESCRIPTION | |
21 | ----------- | |
22 | ||
23 | Displays references available in a local repository along with the associated | |
24 | commit IDs. Results can be filtered using a pattern and tags can be | |
25 | dereferenced into object IDs. Additionally, it can be used to test whether a | |
26 | particular ref exists. | |
27 | ||
3f3d0cea DB |
28 | By default, shows the tags, heads, and remote refs. |
29 | ||
00bf6859 | 30 | The `--exclude-existing` form is a filter that does the inverse. It reads |
33e8fc87 JH |
31 | refs from stdin, one ref per line, and shows those that don't exist in |
32 | the local repository. | |
8bd26c4a | 33 | |
9080a7f1 PS |
34 | The `--exists` form can be used to check for the existence of a single |
35 | references. This form does not verify whether the reference resolves to an | |
36 | actual object. | |
37 | ||
c0990ff3 | 38 | Use of this utility is encouraged in favor of directly accessing files under |
d4900ee4 | 39 | the `.git` directory. |
c0990ff3 JF |
40 | |
41 | OPTIONS | |
42 | ------- | |
43 | ||
3240240f | 44 | --head:: |
c0990ff3 | 45 | |
3f3d0cea | 46 | Show the HEAD reference, even if it would normally be filtered out. |
c0990ff3 | 47 | |
3240240f | 48 | --heads:: |
bd8d6f0d | 49 | --tags:: |
c0990ff3 | 50 | |
3f3d0cea DB |
51 | Limit to "refs/heads" and "refs/tags", respectively. These options |
52 | are not mutually exclusive; when given both, references stored in | |
53 | "refs/heads" and "refs/tags" are displayed. | |
c0990ff3 | 54 | |
3240240f SB |
55 | -d:: |
56 | --dereference:: | |
c0990ff3 | 57 | |
18c4aac0 | 58 | Dereference tags into object IDs as well. They will be shown with `^{}` |
c0990ff3 JF |
59 | appended. |
60 | ||
3240240f | 61 | -s:: |
69932bc6 | 62 | --hash[=<n>]:: |
9581e0fc | 63 | |
00bf6859 SA |
64 | Only show the OID, not the reference name. When combined with |
65 | `--dereference`, the dereferenced tag will still be shown after the OID. | |
9581e0fc | 66 | |
c0990ff3 JF |
67 | --verify:: |
68 | ||
69 | Enable stricter reference checking by requiring an exact ref path. | |
70 | Aside from returning an error code of 1, it will also print an error | |
bcf9626a | 71 | message if `--quiet` was not specified. |
c0990ff3 | 72 | |
9080a7f1 PS |
73 | --exists:: |
74 | ||
75 | Check whether the given reference exists. Returns an exit code of 0 if | |
76 | it does, 2 if it is missing, and 1 in case looking up the reference | |
77 | failed with an error other than the reference being missing. | |
78 | ||
69932bc6 | 79 | --abbrev[=<n>]:: |
2eaf2224 JH |
80 | |
81 | Abbreviate the object name. When using `--hash`, you do | |
69932bc6 | 82 | not have to say `--hash --abbrev`; `--hash=n` would do. |
2eaf2224 | 83 | |
3240240f SB |
84 | -q:: |
85 | --quiet:: | |
c0990ff3 | 86 | |
1307d5e8 PS |
87 | Do not print any results to stdout. Can be used with `--verify` to |
88 | silently check if a reference exists. | |
c0990ff3 | 89 | |
69932bc6 | 90 | --exclude-existing[=<pattern>]:: |
8bd26c4a | 91 | |
00bf6859 SA |
92 | Make `git show-ref` act as a filter that reads refs from stdin of the |
93 | form `^(?:<anything>\s)?<refname>(?:\^{})?$` | |
f1005987 | 94 | and performs the following actions on each: |
18c4aac0 | 95 | (1) strip `^{}` at the end of line if any; |
8bd26c4a JP |
96 | (2) ignore if pattern is provided and does not head-match refname; |
97 | (3) warn if refname is not a well-formed refname and skip; | |
98 | (4) ignore if refname is a ref that exists in the local repository; | |
99 | (5) otherwise output the line. | |
100 | ||
101 | ||
f448e24e | 102 | <pattern>...:: |
c0990ff3 | 103 | |
9fbd8986 MG |
104 | Show references matching one or more patterns. Patterns are matched from |
105 | the end of the full name, and only complete parts are matched, e.g. | |
106 | 'master' matches 'refs/heads/master', 'refs/remotes/origin/master', | |
a58088ab | 107 | 'refs/tags/jedi/master' but not 'refs/heads/mymaster' or |
9fbd8986 | 108 | 'refs/remotes/master/jedi'. |
c0990ff3 JF |
109 | |
110 | OUTPUT | |
111 | ------ | |
112 | ||
00bf6859 SA |
113 | The output is in the format: |
114 | ||
115 | ------------ | |
116 | <oid> SP <ref> LF | |
117 | ------------ | |
118 | ||
119 | For example, | |
c0990ff3 JF |
120 | |
121 | ----------------------------------------------------------------------------- | |
122 | $ git show-ref --head --dereference | |
123 | 832e76a9899f560a90ffd62ae2ce83bbeff58f54 HEAD | |
124 | 832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/master | |
125 | 832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/origin | |
126 | 3521017556c5de4159da4615a39fa4d5d2c279b5 refs/tags/v0.99.9c | |
127 | 6ddc0964034342519a87fe013781abf31c6db6ad refs/tags/v0.99.9c^{} | |
128 | 055e4ae3ae6eb344cbabf2a5256a49ea66040131 refs/tags/v1.0rc4 | |
129 | 423325a2d24638ddcc82ce47be5e40be550f4507 refs/tags/v1.0rc4^{} | |
130 | ... | |
131 | ----------------------------------------------------------------------------- | |
132 | ||
00bf6859 SA |
133 | When using `--hash` (and not `--dereference`), the output is in the format: |
134 | ||
135 | ------------ | |
136 | <oid> LF | |
137 | ------------ | |
138 | ||
139 | For example, | |
9581e0fc CC |
140 | |
141 | ----------------------------------------------------------------------------- | |
142 | $ git show-ref --heads --hash | |
143 | 2e3ba0114a1f52b47df29743d6915d056be13278 | |
144 | 185008ae97960c8d551adcd9e23565194651b5d1 | |
145 | 03adf42c988195b50e1a1935ba5fcbc39b2b029b | |
146 | ... | |
147 | ----------------------------------------------------------------------------- | |
148 | ||
76a8788c NTND |
149 | EXAMPLES |
150 | -------- | |
c0990ff3 JF |
151 | |
152 | To show all references called "master", whether tags or heads or anything | |
153 | else, and regardless of how deep in the reference naming hierarchy they are, | |
154 | use: | |
155 | ||
156 | ----------------------------------------------------------------------------- | |
157 | git show-ref master | |
158 | ----------------------------------------------------------------------------- | |
159 | ||
160 | This will show "refs/heads/master" but also "refs/remote/other-repo/master", | |
ce14cc0b | 161 | if such references exist. |
c0990ff3 | 162 | |
bcf9626a | 163 | When using the `--verify` flag, the command requires an exact path: |
c0990ff3 JF |
164 | |
165 | ----------------------------------------------------------------------------- | |
166 | git show-ref --verify refs/heads/master | |
167 | ----------------------------------------------------------------------------- | |
168 | ||
169 | will only match the exact branch called "master". | |
170 | ||
00bf6859 | 171 | If nothing matches, `git show-ref` will return an error code of 1, |
c0990ff3 JF |
172 | and in the case of verification, it will show an error message. |
173 | ||
00bf6859 | 174 | For scripting, you can ask it to be quiet with the `--quiet` flag, which |
c0990ff3 JF |
175 | allows you to do things like |
176 | ||
177 | ----------------------------------------------------------------------------- | |
b1889c36 | 178 | git show-ref --quiet --verify -- "refs/heads/$headname" || |
c0990ff3 JF |
179 | echo "$headname is not a valid branch" |
180 | ----------------------------------------------------------------------------- | |
181 | ||
182 | to check whether a particular branch exists or not (notice how we don't | |
183 | actually want to show any results, and we want to use the full refname for it | |
184 | in order to not trigger the problem with ambiguous partial matches). | |
185 | ||
00bf6859 | 186 | To show only tags, or only proper branch heads, use `--tags` and/or `--heads` |
c0990ff3 JF |
187 | respectively (using both means that it shows tags and heads, but not other |
188 | random references under the refs/ subdirectory). | |
189 | ||
00bf6859 | 190 | To do automatic tag object dereferencing, use the `-d` or `--dereference` |
c0990ff3 JF |
191 | flag, so you can do |
192 | ||
193 | ----------------------------------------------------------------------------- | |
194 | git show-ref --tags --dereference | |
195 | ----------------------------------------------------------------------------- | |
196 | ||
197 | to get a listing of all tags together with what they dereference. | |
198 | ||
977ed83a JN |
199 | FILES |
200 | ----- | |
201 | `.git/refs/*`, `.git/packed-refs` | |
202 | ||
c0990ff3 JF |
203 | SEE ALSO |
204 | -------- | |
f21e1c5d | 205 | linkgit:git-for-each-ref[1], |
977ed83a JN |
206 | linkgit:git-ls-remote[1], |
207 | linkgit:git-update-ref[1], | |
208 | linkgit:gitrepository-layout[5] | |
c0990ff3 | 209 | |
c0990ff3 JF |
210 | GIT |
211 | --- | |
9e1f0a85 | 212 | Part of the linkgit:git[1] suite |