git-for-each-ref.html

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