blob: e6a61a4aecd07152438bf6087e09ff6923952c6c [file] [log] [blame]
Junio C Hamanoff4b4312006-10-25 22:55:311<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6<meta name="generator" content="AsciiDoc 7.0.2" />
7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
19a { color: blue; }
20a:visited { color: fuchsia; }
21
22em {
23 font-style: italic;
24}
25
26strong {
27 font-weight: bold;
28}
29
30tt {
31 color: navy;
32}
33
34h1, h2, h3, h4, h5, h6 {
35 color: #527bbd;
36 font-family: sans-serif;
37 margin-top: 1.2em;
38 margin-bottom: 0.5em;
39 line-height: 1.3;
40}
41
42h1 {
43 border-bottom: 2px solid silver;
44}
45h2 {
46 border-bottom: 2px solid silver;
47 padding-top: 0.5em;
48}
49
50div.sectionbody {
51 font-family: serif;
52 margin-left: 0;
53}
54
55hr {
56 border: 1px solid silver;
57}
58
59p {
60 margin-top: 0.5em;
61 margin-bottom: 0.5em;
62}
63
64pre {
65 padding: 0;
66 margin: 0;
67}
68
69span#author {
70 color: #527bbd;
71 font-family: sans-serif;
72 font-weight: bold;
73 font-size: 1.2em;
74}
75span#email {
76}
77span#revision {
78 font-family: sans-serif;
79}
80
81div#footer {
82 font-family: sans-serif;
83 font-size: small;
84 border-top: 2px solid silver;
85 padding-top: 0.5em;
86 margin-top: 4.0em;
87}
88div#footer-text {
89 float: left;
90 padding-bottom: 0.5em;
91}
92div#footer-badges {
93 float: right;
94 padding-bottom: 0.5em;
95}
96
97div#preamble,
98div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
99div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
100div.admonitionblock {
101 margin-right: 10%;
102 margin-top: 1.5em;
103 margin-bottom: 1.5em;
104}
105div.admonitionblock {
106 margin-top: 2.5em;
107 margin-bottom: 2.5em;
108}
109
110div.content { /* Block element content. */
111 padding: 0;
112}
113
114/* Block element titles. */
115div.title, caption.title {
116 font-family: sans-serif;
117 font-weight: bold;
118 text-align: left;
119 margin-top: 1.0em;
120 margin-bottom: 0.5em;
121}
122div.title + * {
123 margin-top: 0;
124}
125
126td div.title:first-child {
127 margin-top: 0.0em;
128}
129div.content div.title:first-child {
130 margin-top: 0.0em;
131}
132div.content + div.title {
133 margin-top: 0.0em;
134}
135
136div.sidebarblock > div.content {
137 background: #ffffee;
138 border: 1px solid silver;
139 padding: 0.5em;
140}
141
142div.listingblock > div.content {
143 border: 1px solid silver;
144 background: #f4f4f4;
145 padding: 0.5em;
146}
147
148div.quoteblock > div.content {
149 padding-left: 2.0em;
150}
151div.quoteblock .attribution {
152 text-align: right;
153}
154
155div.admonitionblock .icon {
156 vertical-align: top;
157 font-size: 1.1em;
158 font-weight: bold;
159 text-decoration: underline;
160 color: #527bbd;
161 padding-right: 0.5em;
162}
163div.admonitionblock td.content {
164 padding-left: 0.5em;
165 border-left: 2px solid silver;
166}
167
168div.exampleblock > div.content {
169 border-left: 2px solid silver;
170 padding: 0.5em;
171}
172
173div.verseblock div.content {
174 white-space: pre;
175}
176
177div.imageblock div.content { padding-left: 0; }
178div.imageblock img { border: 1px solid silver; }
179span.image img { border-style: none; }
180
181dl {
182 margin-top: 0.8em;
183 margin-bottom: 0.8em;
184}
185dt {
186 margin-top: 0.5em;
187 margin-bottom: 0;
188 font-style: italic;
189}
190dd > *:first-child {
191 margin-top: 0;
192}
193
194ul, ol {
195 list-style-position: outside;
196}
197ol.olist2 {
198 list-style-type: lower-alpha;
199}
200
201div.tableblock > table {
202 border-color: #527bbd;
203 border-width: 3px;
204}
205thead {
206 font-family: sans-serif;
207 font-weight: bold;
208}
209tfoot {
210 font-weight: bold;
211}
212
213div.hlist {
214 margin-top: 0.8em;
215 margin-bottom: 0.8em;
216}
217td.hlist1 {
218 vertical-align: top;
219 font-style: italic;
220 padding-right: 0.8em;
221}
222td.hlist2 {
223 vertical-align: top;
224}
225
226@media print {
227 div#footer-badges { display: none; }
228}
229include::./stylesheets/xhtml11-manpage.css[]
230/* Workarounds for IE6's broken and incomplete CSS2. */
231
232div.sidebar-content {
233 background: #ffffee;
234 border: 1px solid silver;
235 padding: 0.5em;
236}
237div.sidebar-title, div.image-title {
238 font-family: sans-serif;
239 font-weight: bold;
240 margin-top: 0.0em;
241 margin-bottom: 0.5em;
242}
243
244div.listingblock div.content {
245 border: 1px solid silver;
246 background: #f4f4f4;
247 padding: 0.5em;
248}
249
250div.quoteblock-content {
251 padding-left: 2.0em;
252}
253
254div.exampleblock-content {
255 border-left: 2px solid silver;
256 padding-left: 0.5em;
257}
258</style>
259<title>git-for-each-ref(1)</title>
260</head>
261<body>
262<div id="header">
263<h1>
264git-for-each-ref(1) Manual Page
265</h1>
266<h2>NAME</h2>
267<div class="sectionbody">
268<p>git-for-each-ref -
269 Output information on each ref
270</p>
271</div>
272</div>
273<h2>SYNOPSIS</h2>
274<div class="sectionbody">
Junio C Hamanoa9b8d242007-05-19 04:51:55275<div class="verseblock">
276<div class="content"><em>git-for-each-ref</em> [--count=&lt;count&gt;]*
277 [--shell|--perl|--python|--tcl]
278 [--sort=&lt;key&gt;]* [--format=&lt;format&gt;] [&lt;pattern&gt;]</div></div>
Junio C Hamanoff4b4312006-10-25 22:55:31279</div>
280<h2>DESCRIPTION</h2>
281<div class="sectionbody">
282<p>Iterate over all refs that match <tt>&lt;pattern&gt;</tt> and show them
283according to the given <tt>&lt;format&gt;</tt>, after sorting them according
Junio C Hamano4de43af2006-10-28 21:29:01284to the given set of <tt>&lt;key&gt;</tt>. If <tt>&lt;max&gt;</tt> is given, stop after
Junio C Hamanof9771f62007-01-17 17:42:30285showing that many refs. The interpolated values in <tt>&lt;format&gt;</tt>
Junio C Hamanoff4b4312006-10-25 22:55:31286can optionally be quoted as string literals in the specified
287host language allowing their direct evaluation in that language.</p>
288</div>
289<h2>OPTIONS</h2>
290<div class="sectionbody">
291<dl>
292<dt>
293&lt;count&gt;
294</dt>
295<dd>
296<p>
297 By default the command shows all refs that match
298 <tt>&lt;pattern&gt;</tt>. This option makes it stop after showing
299 that many refs.
300</p>
301</dd>
302<dt>
303&lt;key&gt;
304</dt>
305<dd>
306<p>
307 A field name to sort on. Prefix <tt>-</tt> to sort in
308 descending order of the value. When unspecified,
309 <tt>refname</tt> is used. More than one sort keys can be
310 given.
311</p>
312</dd>
313<dt>
314&lt;format&gt;
315</dt>
316<dd>
317<p>
318 A string that interpolates <tt>%(fieldname)</tt> from the
319 object pointed at by a ref being shown. If <tt>fieldname</tt>
320 is prefixed with an asterisk (<tt>*</tt>) and the ref points
321 at a tag object, the value for the field in the object
322 tag refers is used. When unspecified, defaults to
Junio C Hamano4de43af2006-10-28 21:29:01323 <tt>%(objectname) SPC %(objecttype) TAB %(refname)</tt>.
324 It also interpolates <tt>%%</tt> to <tt>%</tt>, and <tt>%xx</tt> where <tt>xx</tt>
325 are hex digits interpolates to character with hex code
326 <tt>xx</tt>; for example <tt>%00</tt> interpolates to <tt>\0</tt> (NUL),
327 <tt>%09</tt> to <tt>\t</tt> (TAB) and <tt>%0a</tt> to <tt>\n</tt> (LF).
Junio C Hamanoff4b4312006-10-25 22:55:31328</p>
329</dd>
330<dt>
331&lt;pattern&gt;
332</dt>
333<dd>
334<p>
335 If given, the name of the ref is matched against this
336 using fnmatch(3). Refs that do not match the pattern
337 are not shown.
338</p>
339</dd>
340<dt>
Junio C Hamano7ad22dc2007-01-29 02:55:48341--shell, --perl, --python, --tcl
Junio C Hamanoff4b4312006-10-25 22:55:31342</dt>
343<dd>
344<p>
345 If given, strings that substitute <tt>%(fieldname)</tt>
346 placeholders are quoted as string literals suitable for
347 the specified host language. This is meant to produce
348 a scriptlet that can directly be `eval`ed.
349</p>
350</dd>
351</dl>
352</div>
353<h2>FIELD NAMES</h2>
354<div class="sectionbody">
355<p>Various values from structured fields in referenced objects can
356be used to interpolate into the resulting output, or as sort
357keys.</p>
358<p>For all objects, the following names can be used:</p>
359<dl>
360<dt>
361refname
362</dt>
363<dd>
364<p>
Junio C Hamano42f855f2007-02-06 00:09:38365 The name of the ref (the part after $GIT_DIR/).
Junio C Hamanoff4b4312006-10-25 22:55:31366</p>
367</dd>
368<dt>
369objecttype
370</dt>
371<dd>
372<p>
373 The type of the object (<tt>blob</tt>, <tt>tree</tt>, <tt>commit</tt>, <tt>tag</tt>).
374</p>
375</dd>
376<dt>
377objectsize
378</dt>
379<dd>
380<p>
381 The size of the object (the same as <tt>git-cat-file -s</tt> reports).
382</p>
383</dd>
384<dt>
385objectname
386</dt>
387<dd>
388<p>
389 The object name (aka SHA-1).
390</p>
391</dd>
392</dl>
393<p>In addition to the above, for commit and tag objects, the header
394field names (<tt>tree</tt>, <tt>parent</tt>, <tt>object</tt>, <tt>type</tt>, and <tt>tag</tt>) can
395be used to specify the value in the header field.</p>
396<p>Fields that have name-email-date tuple as its value (<tt>author</tt>,
397<tt>committer</tt>, and <tt>tagger</tt>) can be suffixed with <tt>name</tt>, <tt>email</tt>,
398and <tt>date</tt> to extract the named component.</p>
399<p>The first line of the message in a commit and tag object is
400<tt>subject</tt>, the remaining lines are <tt>body</tt>. The whole message
401is <tt>contents</tt>.</p>
402<p>For sorting purposes, fields with numeric values sort in numeric
403order (<tt>objectsize</tt>, <tt>authordate</tt>, <tt>committerdate</tt>, <tt>taggerdate</tt>).
404All other fields are used to sort in their byte-value order.</p>
405<p>In any case, a field name that refers to a field inapplicable to
406the object referred by the ref does not cause an error. It
407returns an empty string instead.</p>
Junio C Hamano1b50ce92007-10-03 12:05:53408<p>As a special case for the date-type fields, you may specify a format for
409the date by adding one of <tt>:default</tt>, <tt>:relative</tt>, <tt>:short</tt>, <tt>:local</tt>,
410<tt>:iso8601</tt> or <tt>:rfc2822</tt> to the end of the fieldname; e.g.
411<tt>%(taggerdate:relative)</tt>.</p>
Junio C Hamanoff4b4312006-10-25 22:55:31412</div>
413<h2>EXAMPLES</h2>
414<div class="sectionbody">
415<p>An example directly producing formatted text. Show the most recent
4163 tagged commits::</p>
417<div class="listingblock">
418<div class="content">
419<pre><tt>#!/bin/sh
420
421git-for-each-ref --count=3 --sort='-*authordate' \
422--format='From: %(*authorname) %(*authoremail)
423Subject: %(*subject)
424Date: %(*authordate)
425Ref: %(*refname)
426
427%(*body)
428' 'refs/tags'</tt></pre>
429</div></div>
430<p>A simple example showing the use of shell eval on the output,
431demonstrating the use of --shell. List the prefixes of all heads::</p>
432<div class="listingblock">
433<div class="content">
434<pre><tt>#!/bin/sh
435
436git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \
437while read entry
438do
439 eval "$entry"
440 echo `dirname $ref`
441done</tt></pre>
442</div></div>
443<p>A bit more elaborate report on tags, demonstrating that the format
444may be an entire script::</p>
445<div class="listingblock">
446<div class="content">
447<pre><tt>#!/bin/sh
448
449fmt='
450 r=%(refname)
451 t=%(*objecttype)
452 T=${r#refs/tags/}
453
454 o=%(*objectname)
455 n=%(*authorname)
456 e=%(*authoremail)
457 s=%(*subject)
458 d=%(*authordate)
459 b=%(*body)
460
461 kind=Tag
462 if test "z$t" = z
463 then
464 # could be a lightweight tag
465 t=%(objecttype)
466 kind="Lightweight tag"
467 o=%(objectname)
468 n=%(authorname)
469 e=%(authoremail)
470 s=%(subject)
471 d=%(authordate)
472 b=%(body)
473 fi
474 echo "$kind $T points at a $t object $o"
475 if test "z$t" = zcommit
476 then
477 echo "The commit was authored by $n $e
478at $d, and titled
479
480 $s
481
482Its message reads as:
483"
484 echo "$b" | sed -e "s/^/ /"
485 echo
486 fi
487'
488
489eval=`git-for-each-ref --shell --format="$fmt" \
490 --sort='*objecttype' \
491 --sort=-taggerdate \
492 refs/tags`
493eval "$eval"</tt></pre>
494</div></div>
495</div>
496<div id="footer">
497<div id="footer-text">
Junio C Hamano35738e82008-01-07 07:55:46498Last updated 07-Jan-2008 07:50:21 UTC
Junio C Hamanoff4b4312006-10-25 22:55:31499</div>
500</div>
501</body>
502</html>