doc/source/en/TortoiseGit/git_doc/git-show-ref.html.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-show-ref(1)">\r
   5 <articleinfo>\r
   6     <title>git-show-ref(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-show-ref(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-show-ref - List references in a local repository</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git show-ref</emphasis> [-q|--quiet] [--verify] [-h|--head] [-d|--dereference]\r
  19              [-s|--hash] [--abbrev] [--tags] [--heads] [--] &lt;pattern&gt;&#8230;\r
  20 <emphasis>git show-ref</emphasis> --exclude-existing[=pattern]</literallayout>\r
  21 </blockquote>\r
  22 </simplesect>\r
  23 <simplesect id="_description">\r
  24 <title>DESCRIPTION</title>\r
  25 <simpara>Displays references available in a local repository along with the associated\r
  26 commit IDs. Results can be filtered using a pattern and tags can be\r
  27 dereferenced into object IDs. Additionally, it can be used to test whether a\r
  28 particular ref exists.</simpara>\r
  29 <simpara>The --exclude-existing form is a filter that does the inverse, it shows the\r
  30 refs from stdin that don&#8217;t exist in the local repository.</simpara>\r
  31 <simpara>Use of this utility is encouraged in favor of directly accessing files under\r
  32 in the <literal>.git</literal> directory.</simpara>\r
  33 </simplesect>\r
  34 <simplesect id="_options">\r
  35 <title>OPTIONS</title>\r
  36 <variablelist>\r
  37 <varlistentry>\r
  38 <term>\r
  39 -h\r
  40 </term>\r
  41 <term>\r
  42 --head\r
  43 </term>\r
  44 <listitem>\r
  45 <simpara>\r
  46         Show the HEAD reference.\r
  47 </simpara>\r
  48 </listitem>\r
  49 </varlistentry>\r
  50 <varlistentry>\r
  51 <term>\r
  52 --tags\r
  53 </term>\r
  54 <term>\r
  55 --heads\r
  56 </term>\r
  57 <listitem>\r
  58 <simpara>\r
  59         Limit to only "refs/heads" and "refs/tags", respectively.  These\r
  60         options are not mutually exclusive; when given both, references stored\r
  61         in "refs/heads" and "refs/tags" are displayed.\r
  62 </simpara>\r
  63 </listitem>\r
  64 </varlistentry>\r
  65 <varlistentry>\r
  66 <term>\r
  67 -d\r
  68 </term>\r
  69 <term>\r
  70 --dereference\r
  71 </term>\r
  72 <listitem>\r
  73 <simpara>\r
  74         Dereference tags into object IDs as well. They will be shown with "^{}"\r
  75         appended.\r
  76 </simpara>\r
  77 </listitem>\r
  78 </varlistentry>\r
  79 <varlistentry>\r
  80 <term>\r
  81 -s\r
  82 </term>\r
  83 <term>\r
  84 --hash\r
  85 </term>\r
  86 <listitem>\r
  87 <simpara>\r
  88         Only show the SHA1 hash, not the reference name. When also using\r
  89         --dereference the dereferenced tag will still be shown after the SHA1.\r
  90 </simpara>\r
  91 </listitem>\r
  92 </varlistentry>\r
  93 <varlistentry>\r
  94 <term>\r
  95 --verify\r
  96 </term>\r
  97 <listitem>\r
  98 <simpara>\r
  99         Enable stricter reference checking by requiring an exact ref path.\r
 100         Aside from returning an error code of 1, it will also print an error\r
 101         message if <emphasis>--quiet</emphasis> was not specified.\r
 102 </simpara>\r
 103 </listitem>\r
 104 </varlistentry>\r
 105 <varlistentry>\r
 106 <term>\r
 107 --abbrev\r
 108 </term>\r
 109 <term>\r
 110 --abbrev=len\r
 111 </term>\r
 112 <listitem>\r
 113 <simpara>\r
 114         Abbreviate the object name.  When using <literal>--hash</literal>, you do\r
 115         not have to say <literal>--hash --abbrev</literal>; <literal>--hash=len</literal> would do.\r
 116 </simpara>\r
 117 </listitem>\r
 118 </varlistentry>\r
 119 <varlistentry>\r
 120 <term>\r
 121 -q\r
 122 </term>\r
 123 <term>\r
 124 --quiet\r
 125 </term>\r
 126 <listitem>\r
 127 <simpara>\r
 128         Do not print any results to stdout. When combined with <emphasis>--verify</emphasis> this\r
 129         can be used to silently check if a reference exists.\r
 130 </simpara>\r
 131 </listitem>\r
 132 </varlistentry>\r
 133 <varlistentry>\r
 134 <term>\r
 135 --exclude-existing\r
 136 </term>\r
 137 <term>\r
 138 --exclude-existing=pattern\r
 139 </term>\r
 140 <listitem>\r
 141 <simpara>\r
 142         Make <emphasis>git-show-ref</emphasis> act as a filter that reads refs from stdin of the\r
 143         form "<superscript>(?:&lt;anything&gt;\s)?&lt;refname&gt;(?:\</superscript>{})?$" and performs the\r
 144         following actions on each:\r
 145         (1) strip "^{}" at the end of line if any;\r
 146         (2) ignore if pattern is provided and does not head-match refname;\r
 147         (3) warn if refname is not a well-formed refname and skip;\r
 148         (4) ignore if refname is a ref that exists in the local repository;\r
 149         (5) otherwise output the line.\r
 150 </simpara>\r
 151 </listitem>\r
 152 </varlistentry>\r
 153 <varlistentry>\r
 154 <term>\r
 155 &lt;pattern&gt;&#8230;\r
 156 </term>\r
 157 <listitem>\r
 158 <simpara>\r
 159         Show references matching one or more patterns.\r
 160 </simpara>\r
 161 </listitem>\r
 162 </varlistentry>\r
 163 </variablelist>\r
 164 </simplesect>\r
 165 <simplesect id="_output">\r
 166 <title>OUTPUT</title>\r
 167 <simpara>The output is in the format: <emphasis>&lt;SHA-1 ID&gt;</emphasis> <emphasis>&lt;space&gt;</emphasis> <emphasis>&lt;reference name&gt;</emphasis>.</simpara>\r
 168 <literallayout>$ git show-ref --head --dereference\r
 169 832e76a9899f560a90ffd62ae2ce83bbeff58f54 HEAD\r
 170 832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/master\r
 171 832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/origin\r
 172 3521017556c5de4159da4615a39fa4d5d2c279b5 refs/tags/v0.99.9c\r
 173 6ddc0964034342519a87fe013781abf31c6db6ad refs/tags/v0.99.9c^{}\r
 174 055e4ae3ae6eb344cbabf2a5256a49ea66040131 refs/tags/v1.0rc4\r
 175 423325a2d24638ddcc82ce47be5e40be550f4507 refs/tags/v1.0rc4^{}\r
 176 ...</literallayout>\r
 177 <simpara>When using --hash (and not --dereference) the output format is: <emphasis>&lt;SHA-1 ID&gt;</emphasis></simpara>\r
 178 <literallayout>$ git show-ref --heads --hash\r
 179 2e3ba0114a1f52b47df29743d6915d056be13278\r
 180 185008ae97960c8d551adcd9e23565194651b5d1\r
 181 03adf42c988195b50e1a1935ba5fcbc39b2b029b\r
 182 ...</literallayout>\r
 183 </simplesect>\r
 184 <simplesect id="_example">\r
 185 <title>EXAMPLE</title>\r
 186 <simpara>To show all references called "master", whether tags or heads or anything\r
 187 else, and regardless of how deep in the reference naming hierarchy they are,\r
 188 use:</simpara>\r
 189 <literallayout>        git show-ref master</literallayout>\r
 190 <simpara>This will show "refs/heads/master" but also "refs/remote/other-repo/master",\r
 191 if such references exists.</simpara>\r
 192 <simpara>When using the <emphasis>--verify</emphasis> flag, the command requires an exact path:</simpara>\r
 193 <literallayout>        git show-ref --verify refs/heads/master</literallayout>\r
 194 <simpara>will only match the exact branch called "master".</simpara>\r
 195 <simpara>If nothing matches, <emphasis>git-show-ref</emphasis> will return an error code of 1,\r
 196 and in the case of verification, it will show an error message.</simpara>\r
 197 <simpara>For scripting, you can ask it to be quiet with the "--quiet" flag, which\r
 198 allows you to do things like</simpara>\r
 199 <literallayout>        git show-ref --quiet --verify -- "refs/heads/$headname" ||\r
 200                 echo "$headname is not a valid branch"</literallayout>\r
 201 <simpara>to check whether a particular branch exists or not (notice how we don&#8217;t\r
 202 actually want to show any results, and we want to use the full refname for it\r
 203 in order to not trigger the problem with ambiguous partial matches).</simpara>\r
 204 <simpara>To show only tags, or only proper branch heads, use "--tags" and/or "--heads"\r
 205 respectively (using both means that it shows tags and heads, but not other\r
 206 random references under the refs/ subdirectory).</simpara>\r
 207 <simpara>To do automatic tag object dereferencing, use the "-d" or "--dereference"\r
 208 flag, so you can do</simpara>\r
 209 <literallayout>        git show-ref --tags --dereference</literallayout>\r
 210 <simpara>to get a listing of all tags together with what they dereference.</simpara>\r
 211 </simplesect>\r
 212 <simplesect id="_see_also">\r
 213 <title>SEE ALSO</title>\r
 214 <simpara><xref linkend="git-ls-remote(1)"/></simpara>\r
 215 </simplesect>\r
 216 <simplesect id="_authors">\r
 217 <title>AUTHORS</title>\r
 218 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;.\r
 219 Man page by Jonas Fonseca &lt;<ulink url="mailto:fonseca@diku.dk">fonseca@diku.dk</ulink>&gt;.</simpara>\r
 220 </simplesect>\r
 221 <simplesect id="_git">\r
 222 <title>GIT</title>\r
 223 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 224 </simplesect>\r
 225 </article>\r