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