OSDN Git Service

Add Git official document to help
[tortoisegit/TortoiseGitJp.git] / 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