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