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