MyFirstObjectWalk.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>My First Object Walk</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="article">
 736 <div id="header">
 737 <h1>My First Object Walk</h1>
 738 <span id="revdate">2023-06-13</span>
 739 </div>
 740 <div id="content">
 741 <div class="sect1">
 742 <h2 id="_what_8217_s_an_object_walk">What&#8217;s an Object Walk?</h2>
 743 <div class="sectionbody">
 744 <div class="paragraph"><p>The object walk is a key concept in Git - this is the process that underpins
 745 operations like object transfer and fsck. Beginning from a given commit, the
 746 list of objects is found by walking parent relationships between commits (commit
 747 X based on commit W) and containment relationships between objects (tree Y is
 748 contained within commit X, and blob Z is located within tree Y, giving our
 749 working tree for commit X something like <code>y/z.txt</code>).</p></div>
 750 <div class="paragraph"><p>A related concept is the revision walk, which is focused on commit objects and
 751 their parent relationships and does not delve into other object types. The
 752 revision walk is used for operations like <code>git log</code>.</p></div>
 753 <div class="sect2">
 754 <h3 id="_related_reading">Related Reading</h3>
 755 <div class="ulist"><ul>
 756 <li>
 757 <p>
 758 <code>Documentation/user-manual.txt</code> under "Hacking Git" contains some coverage of
 759   the revision walker in its various incarnations.
 760 </p>
 761 </li>
 762 <li>
 763 <p>
 764 <code>revision.h</code>
 765 </p>
 766 </li>
 767 <li>
 768 <p>
 769 <a href="https://eagain.net/articles/git-for-computer-scientists/">Git for Computer Scientists</a>
 770   gives a good overview of the types of objects in Git and what your object
 771   walk is really describing.
 772 </p>
 773 </li>
 774 </ul></div>
 775 </div>
 776 </div>
 777 </div>
 778 <div class="sect1">
 779 <h2 id="_setting_up">Setting Up</h2>
 780 <div class="sectionbody">
 781 <div class="paragraph"><p>Create a new branch from <code>master</code>.</p></div>
 782 <div class="listingblock">
 783 <div class="content">
 784 <pre><code>git checkout -b revwalk origin/master</code></pre>
 785 </div></div>
 786 <div class="paragraph"><p>We&#8217;ll put our fiddling into a new command. For fun, let&#8217;s name it <code>git walken</code>.
 787 Open up a new file <code>builtin/walken.c</code> and set up the command handler:</p></div>
 788 <div class="listingblock">
 789 <div class="content">
 790 <pre><code>/*
 791  * "git walken"
 792  *
 793  * Part of the "My First Object Walk" tutorial.
 794  */
 795
 796 #include "builtin.h"
 797
 798 int cmd_walken(int argc, const char **argv, const char *prefix)
 799 {
 800         trace_printf(_("cmd_walken incoming...\n"));
 801         return 0;
 802 }</code></pre>
 803 </div></div>
 804 <div class="admonitionblock">
 805 <table><tr>
 806 <td class="icon">
 807 <div class="title">Note</div>
 808 </td>
 809 <td class="content"><code>trace_printf()</code> differs from <code>printf()</code> in that it can be turned on or
 810 off at runtime. For the purposes of this tutorial, we will write <code>walken</code> as
 811 though it is intended for use as a "plumbing" command: that is, a command which
 812 is used primarily in scripts, rather than interactively by humans (a "porcelain"
 813 command). So we will send our debug output to <code>trace_printf()</code> instead. When
 814 running, enable trace output by setting the environment variable <code>GIT_TRACE</code>.</td>
 815 </tr></table>
 816 </div>
 817 <div class="paragraph"><p>Add usage text and <code>-h</code> handling, like all subcommands should consistently do
 818 (our test suite will notice and complain if you fail to do so).
 819 We&#8217;ll need to include the <code>parse-options.h</code> header.</p></div>
 820 <div class="listingblock">
 821 <div class="content">
 822 <pre><code>#include "parse-options.h"
 823
 824 ...
 825
 826 int cmd_walken(int argc, const char **argv, const char *prefix)
 827 {
 828         const char * const walken_usage[] = {
 829                 N_("git walken"),
 830                 NULL,
 831         };
 832         struct option options[] = {
 833                 OPT_END()
 834         };
 835
 836         argc = parse_options(argc, argv, prefix, options, walken_usage, 0);
 837
 838         ...
 839 }</code></pre>
 840 </div></div>
 841 <div class="paragraph"><p>Also add the relevant line in <code>builtin.h</code> near <code>cmd_whatchanged()</code>:</p></div>
 842 <div class="listingblock">
 843 <div class="content">
 844 <pre><code>int cmd_walken(int argc, const char **argv, const char *prefix);</code></pre>
 845 </div></div>
 846 <div class="paragraph"><p>Include the command in <code>git.c</code> in <code>commands[]</code> near the entry for <code>whatchanged</code>,
 847 maintaining alphabetical ordering:</p></div>
 848 <div class="listingblock">
 849 <div class="content">
 850 <pre><code>{ "walken", cmd_walken, RUN_SETUP },</code></pre>
 851 </div></div>
 852 <div class="paragraph"><p>Add it to the <code>Makefile</code> near the line for <code>builtin/worktree.o</code>:</p></div>
 853 <div class="listingblock">
 854 <div class="content">
 855 <pre><code>BUILTIN_OBJS += builtin/walken.o</code></pre>
 856 </div></div>
 857 <div class="paragraph"><p>Build and test out your command, without forgetting to ensure the <code>DEVELOPER</code>
 858 flag is set, and with <code>GIT_TRACE</code> enabled so the debug output can be seen:</p></div>
 859 <div class="listingblock">
 860 <div class="content">
 861 <pre><code>$ echo DEVELOPER=1 &gt;&gt;config.mak
 862 $ make
 863 $ GIT_TRACE=1 ./bin-wrappers/git walken</code></pre>
 864 </div></div>
 865 <div class="admonitionblock">
 866 <table><tr>
 867 <td class="icon">
 868 <div class="title">Note</div>
 869 </td>
 870 <td class="content">For a more exhaustive overview of the new command process, take a look at
 871 <code>Documentation/MyFirstContribution.txt</code>.</td>
 872 </tr></table>
 873 </div>
 874 <div class="admonitionblock">
 875 <table><tr>
 876 <td class="icon">
 877 <div class="title">Note</div>
 878 </td>
 879 <td class="content">A reference implementation can be found at
 880 <a href="https://github.com/nasamuffin/git/tree/revwalk">https://github.com/nasamuffin/git/tree/revwalk</a>.</td>
 881 </tr></table>
 882 </div>
 883 <div class="sect2">
 884 <h3 id="_code_struct_rev_cmdline_info_code"><code>struct rev_cmdline_info</code></h3>
 885 <div class="paragraph"><p>The definition of <code>struct rev_cmdline_info</code> can be found in <code>revision.h</code>.</p></div>
 886 <div class="paragraph"><p>This struct is contained within the <code>rev_info</code> struct and is used to reflect
 887 parameters provided by the user over the CLI.</p></div>
 888 <div class="paragraph"><p><code>nr</code> represents the number of <code>rev_cmdline_entry</code> present in the array.</p></div>
 889 <div class="paragraph"><p><code>alloc</code> is used by the <code>ALLOC_GROW</code> macro. Check <code>cache.h</code> - this variable is
 890 used to track the allocated size of the list.</p></div>
 891 <div class="paragraph"><p>Per entry, we find:</p></div>
 892 <div class="paragraph"><p><code>item</code> is the object provided upon which to base the object walk. Items in Git
 893 can be blobs, trees, commits, or tags. (See <code>Documentation/gittutorial-2.txt</code>.)</p></div>
 894 <div class="paragraph"><p><code>name</code> is the object ID (OID) of the object - a hex string you may be familiar
 895 with from using Git to organize your source in the past. Check the tutorial
 896 mentioned above towards the top for a discussion of where the OID can come
 897 from.</p></div>
 898 <div class="paragraph"><p><code>whence</code> indicates some information about what to do with the parents of the
 899 specified object. We&#8217;ll explore this flag more later on; take a look at
 900 <code>Documentation/revisions.txt</code> to get an idea of what could set the <code>whence</code>
 901 value.</p></div>
 902 <div class="paragraph"><p><code>flags</code> are used to hint the beginning of the revision walk and are the first
 903 block under the <code>#include`s in `revision.h</code>. The most likely ones to be set in
 904 the <code>rev_cmdline_info</code> are <code>UNINTERESTING</code> and <code>BOTTOM</code>, but these same flags
 905 can be used during the walk, as well.</p></div>
 906 </div>
 907 <div class="sect2">
 908 <h3 id="_code_struct_rev_info_code"><code>struct rev_info</code></h3>
 909 <div class="paragraph"><p>This one is quite a bit longer, and many fields are only used during the walk
 910 by <code>revision.c</code> - not configuration options. Most of the configurable flags in
 911 <code>struct rev_info</code> have a mirror in <code>Documentation/rev-list-options.txt</code>. It&#8217;s a
 912 good idea to take some time and read through that document.</p></div>
 913 </div>
 914 </div>
 915 </div>
 916 <div class="sect1">
 917 <h2 id="_basic_commit_walk">Basic Commit Walk</h2>
 918 <div class="sectionbody">
 919 <div class="paragraph"><p>First, let&#8217;s see if we can replicate the output of <code>git log --oneline</code>. We&#8217;ll
 920 refer back to the implementation frequently to discover norms when performing
 921 an object walk of our own.</p></div>
 922 <div class="paragraph"><p>To do so, we&#8217;ll first find all the commits, in order, which preceded the current
 923 commit. We&#8217;ll extract the name and subject of the commit from each.</p></div>
 924 <div class="paragraph"><p>Ideally, we will also be able to find out which ones are currently at the tip of
 925 various branches.</p></div>
 926 <div class="sect2">
 927 <h3 id="_setting_up_2">Setting Up</h3>
 928 <div class="paragraph"><p>Preparing for your object walk has some distinct stages.</p></div>
 929 <div class="olist arabic"><ol class="arabic">
 930 <li>
 931 <p>
 932 Perform default setup for this mode, and others which may be invoked.
 933 </p>
 934 </li>
 935 <li>
 936 <p>
 937 Check configuration files for relevant settings.
 938 </p>
 939 </li>
 940 <li>
 941 <p>
 942 Set up the <code>rev_info</code> struct.
 943 </p>
 944 </li>
 945 <li>
 946 <p>
 947 Tweak the initialized <code>rev_info</code> to suit the current walk.
 948 </p>
 949 </li>
 950 <li>
 951 <p>
 952 Prepare the <code>rev_info</code> for the walk.
 953 </p>
 954 </li>
 955 <li>
 956 <p>
 957 Iterate over the objects, processing each one.
 958 </p>
 959 </li>
 960 </ol></div>
 961 <div class="sect3">
 962 <h4 id="_default_setups">Default Setups</h4>
 963 <div class="paragraph"><p>Before examining configuration files which may modify command behavior, set up
 964 default state for switches or options your command may have. If your command
 965 utilizes other Git components, ask them to set up their default states as well.
 966 For instance, <code>git log</code> takes advantage of <code>grep</code> and <code>diff</code> functionality, so
 967 its <code>init_log_defaults()</code> sets its own state (<code>decoration_style</code>) and asks
 968 <code>grep</code> and <code>diff</code> to initialize themselves by calling each of their
 969 initialization functions.</p></div>
 970 </div>
 971 <div class="sect3">
 972 <h4 id="_configuring_from_code_gitconfig_code">Configuring From <code>.gitconfig</code></h4>
 973 <div class="paragraph"><p>Next, we should have a look at any relevant configuration settings (i.e.,
 974 settings readable and settable from <code>git config</code>). This is done by providing a
 975 callback to <code>git_config()</code>; within that callback, you can also invoke methods
 976 from other components you may need that need to intercept these options. Your
 977 callback will be invoked once per each configuration value which Git knows about
 978 (global, local, worktree, etc.).</p></div>
 979 <div class="paragraph"><p>Similarly to the default values, we don&#8217;t have anything to do here yet
 980 ourselves; however, we should call <code>git_default_config()</code> if we aren&#8217;t calling
 981 any other existing config callbacks.</p></div>
 982 <div class="paragraph"><p>Add a new function to <code>builtin/walken.c</code>.
 983 We&#8217;ll also need to include the <code>config.h</code> header:</p></div>
 984 <div class="listingblock">
 985 <div class="content">
 986 <pre><code>#include "config.h"
 987
 988 ...
 989
 990 static int git_walken_config(const char *var, const char *value, void *cb)
 991 {
 992         /*
 993          * For now, we don't have any custom configuration, so fall back to
 994          * the default config.
 995          */
 996         return git_default_config(var, value, cb);
 997 }</code></pre>
 998 </div></div>
 999 <div class="paragraph"><p>Make sure to invoke <code>git_config()</code> with it in your <code>cmd_walken()</code>:</p></div>
1000 <div class="listingblock">
1001 <div class="content">
1002 <pre><code>int cmd_walken(int argc, const char **argv, const char *prefix)
1003 {
1004         ...
1005
1006         git_config(git_walken_config, NULL);
1007
1008         ...
1009 }</code></pre>
1010 </div></div>
1011 </div>
1012 <div class="sect3">
1013 <h4 id="_setting_up_code_rev_info_code">Setting Up <code>rev_info</code></h4>
1014 <div class="paragraph"><p>Now that we&#8217;ve gathered external configuration and options, it&#8217;s time to
1015 initialize the <code>rev_info</code> object which we will use to perform the walk. This is
1016 typically done by calling <code>repo_init_revisions()</code> with the repository you intend
1017 to target, as well as the <code>prefix</code> argument of <code>cmd_walken</code> and your <code>rev_info</code>
1018 struct.</p></div>
1019 <div class="paragraph"><p>Add the <code>struct rev_info</code> and the <code>repo_init_revisions()</code> call.
1020 We&#8217;ll also need to include the <code>revision.h</code> header:</p></div>
1021 <div class="listingblock">
1022 <div class="content">
1023 <pre><code>#include "revision.h"
1024
1025 ...
1026
1027 int cmd_walken(int argc, const char **argv, const char *prefix)
1028 {
1029         /* This can go wherever you like in your declarations.*/
1030         struct rev_info rev;
1031         ...
1032
1033         /* This should go after the git_config() call. */
1034         repo_init_revisions(the_repository, &amp;rev, prefix);
1035
1036         ...
1037 }</code></pre>
1038 </div></div>
1039 </div>
1040 <div class="sect3">
1041 <h4 id="_tweaking_code_rev_info_code_for_the_walk">Tweaking <code>rev_info</code> For the Walk</h4>
1042 <div class="paragraph"><p>We&#8217;re getting close, but we&#8217;re still not quite ready to go. Now that <code>rev</code> is
1043 initialized, we can modify it to fit our needs. This is usually done within a
1044 helper for clarity, so let&#8217;s add one:</p></div>
1045 <div class="listingblock">
1046 <div class="content">
1047 <pre><code>static void final_rev_info_setup(struct rev_info *rev)
1048 {
1049         /*
1050          * We want to mimic the appearance of `git log --oneline`, so let's
1051          * force oneline format.
1052          */
1053         get_commit_format("oneline", rev);
1054
1055         /* Start our object walk at HEAD. */
1056         add_head_to_pending(rev);
1057 }</code></pre>
1058 </div></div>
1059 <div class="admonitionblock">
1060 <table><tr>
1061 <td class="icon">
1062 <div class="title">Note</div>
1063 </td>
1064 <td class="content">
1065 <div class="paragraph"><p>Instead of using the shorthand <code>add_head_to_pending()</code>, you could do
1066 something like this:</p></div>
1067 <div class="listingblock">
1068 <div class="content">
1069 <pre><code>        struct setup_revision_opt opt;
1070
1071         memset(&amp;opt, 0, sizeof(opt));
1072         opt.def = "HEAD";
1073         opt.revarg_opt = REVARG_COMMITTISH;
1074         setup_revisions(argc, argv, rev, &amp;opt);</code></pre>
1075 </div></div>
1076 <div class="paragraph"><p>Using a <code>setup_revision_opt</code> gives you finer control over your walk&#8217;s starting
1077 point.</p></div>
1078 </td>
1079 </tr></table>
1080 </div>
1081 <div class="paragraph"><p>Then let&#8217;s invoke <code>final_rev_info_setup()</code> after the call to
1082 <code>repo_init_revisions()</code>:</p></div>
1083 <div class="listingblock">
1084 <div class="content">
1085 <pre><code>int cmd_walken(int argc, const char **argv, const char *prefix)
1086 {
1087         ...
1088
1089         final_rev_info_setup(&amp;rev);
1090
1091         ...
1092 }</code></pre>
1093 </div></div>
1094 <div class="paragraph"><p>Later, we may wish to add more arguments to <code>final_rev_info_setup()</code>. But for
1095 now, this is all we need.</p></div>
1096 </div>
1097 <div class="sect3">
1098 <h4 id="_preparing_code_rev_info_code_for_the_walk">Preparing <code>rev_info</code> For the Walk</h4>
1099 <div class="paragraph"><p>Now that <code>rev</code> is all initialized and configured, we&#8217;ve got one more setup step
1100 before we get rolling. We can do this in a helper, which will both prepare the
1101 <code>rev_info</code> for the walk, and perform the walk itself. Let&#8217;s start the helper
1102 with the call to <code>prepare_revision_walk()</code>, which can return an error without
1103 dying on its own:</p></div>
1104 <div class="listingblock">
1105 <div class="content">
1106 <pre><code>static void walken_commit_walk(struct rev_info *rev)
1107 {
1108         if (prepare_revision_walk(rev))
1109                 die(_("revision walk setup failed"));
1110 }</code></pre>
1111 </div></div>
1112 <div class="admonitionblock">
1113 <table><tr>
1114 <td class="icon">
1115 <div class="title">Note</div>
1116 </td>
1117 <td class="content"><code>die()</code> prints to <code>stderr</code> and exits the program. Since it will print to
1118 <code>stderr</code> it&#8217;s likely to be seen by a human, so we will localize it.</td>
1119 </tr></table>
1120 </div>
1121 </div>
1122 <div class="sect3">
1123 <h4 id="_performing_the_walk">Performing the Walk!</h4>
1124 <div class="paragraph"><p>Finally! We are ready to begin the walk itself. Now we can see that <code>rev_info</code>
1125 can also be used as an iterator; we move to the next item in the walk by using
1126 <code>get_revision()</code> repeatedly. Add the listed variable declarations at the top and
1127 the walk loop below the <code>prepare_revision_walk()</code> call within your
1128 <code>walken_commit_walk()</code>:</p></div>
1129 <div class="listingblock">
1130 <div class="content">
1131 <pre><code>static void walken_commit_walk(struct rev_info *rev)
1132 {
1133         struct commit *commit;
1134         struct strbuf prettybuf = STRBUF_INIT;
1135
1136         ...
1137
1138         while ((commit = get_revision(rev))) {
1139                 strbuf_reset(&amp;prettybuf);
1140                 pp_commit_easy(CMIT_FMT_ONELINE, commit, &amp;prettybuf);
1141                 puts(prettybuf.buf);
1142         }
1143         strbuf_release(&amp;prettybuf);
1144 }</code></pre>
1145 </div></div>
1146 <div class="admonitionblock">
1147 <table><tr>
1148 <td class="icon">
1149 <div class="title">Note</div>
1150 </td>
1151 <td class="content"><code>puts()</code> prints a <code>char*</code> to <code>stdout</code>. Since this is the part of the
1152 command we expect to be machine-parsed, we&#8217;re sending it directly to stdout.</td>
1153 </tr></table>
1154 </div>
1155 <div class="paragraph"><p>Give it a shot.</p></div>
1156 <div class="listingblock">
1157 <div class="content">
1158 <pre><code>$ make
1159 $ ./bin-wrappers/git walken</code></pre>
1160 </div></div>
1161 <div class="paragraph"><p>You should see all of the subject lines of all the commits in
1162 your tree&#8217;s history, in order, ending with the initial commit, "Initial revision
1163 of "git", the information manager from hell". Congratulations! You&#8217;ve written
1164 your first revision walk. You can play with printing some additional fields
1165 from each commit if you&#8217;re curious; have a look at the functions available in
1166 <code>commit.h</code>.</p></div>
1167 </div>
1168 </div>
1169 <div class="sect2">
1170 <h3 id="_adding_a_filter">Adding a Filter</h3>
1171 <div class="paragraph"><p>Next, let&#8217;s try to filter the commits we see based on their author. This is
1172 equivalent to running <code>git log --author=&lt;pattern&gt;</code>. We can add a filter by
1173 modifying <code>rev_info.grep_filter</code>, which is a <code>struct grep_opt</code>.</p></div>
1174 <div class="paragraph"><p>First some setup. Add <code>grep_config()</code> to <code>git_walken_config()</code>:</p></div>
1175 <div class="listingblock">
1176 <div class="content">
1177 <pre><code>static int git_walken_config(const char *var, const char *value, void *cb)
1178 {
1179         grep_config(var, value, cb);
1180         return git_default_config(var, value, cb);
1181 }</code></pre>
1182 </div></div>
1183 <div class="paragraph"><p>Next, we can modify the <code>grep_filter</code>. This is done with convenience functions
1184 found in <code>grep.h</code>. For fun, we&#8217;re filtering to only commits from folks using a
1185 <code>gmail.com</code> email address - a not-very-precise guess at who may be working on
1186 Git as a hobby. Since we&#8217;re checking the author, which is a specific line in the
1187 header, we&#8217;ll use the <code>append_header_grep_pattern()</code> helper. We can use
1188 the <code>enum grep_header_field</code> to indicate which part of the commit header we want
1189 to search.</p></div>
1190 <div class="paragraph"><p>In <code>final_rev_info_setup()</code>, add your filter line:</p></div>
1191 <div class="listingblock">
1192 <div class="content">
1193 <pre><code>static void final_rev_info_setup(int argc, const char **argv,
1194                 const char *prefix, struct rev_info *rev)
1195 {
1196         ...
1197
1198         append_header_grep_pattern(&amp;rev-&gt;grep_filter, GREP_HEADER_AUTHOR,
1199                 "gmail");
1200         compile_grep_patterns(&amp;rev-&gt;grep_filter);
1201
1202         ...
1203 }</code></pre>
1204 </div></div>
1205 <div class="paragraph"><p><code>append_header_grep_pattern()</code> adds your new "gmail" pattern to <code>rev_info</code>, but
1206 it won&#8217;t work unless we compile it with <code>compile_grep_patterns()</code>.</p></div>
1207 <div class="admonitionblock">
1208 <table><tr>
1209 <td class="icon">
1210 <div class="title">Note</div>
1211 </td>
1212 <td class="content">If you are using <code>setup_revisions()</code> (for example, if you are passing a
1213 <code>setup_revision_opt</code> instead of using <code>add_head_to_pending()</code>), you don&#8217;t need
1214 to call <code>compile_grep_patterns()</code> because <code>setup_revisions()</code> calls it for you.</td>
1215 </tr></table>
1216 </div>
1217 <div class="admonitionblock">
1218 <table><tr>
1219 <td class="icon">
1220 <div class="title">Note</div>
1221 </td>
1222 <td class="content">We could add the same filter via the <code>append_grep_pattern()</code> helper if we
1223 wanted to, but <code>append_header_grep_pattern()</code> adds the <code>enum grep_context</code> and
1224 <code>enum grep_pat_token</code> for us.</td>
1225 </tr></table>
1226 </div>
1227 </div>
1228 <div class="sect2">
1229 <h3 id="_changing_the_order">Changing the Order</h3>
1230 <div class="paragraph"><p>There are a few ways that we can change the order of the commits during a
1231 revision walk. Firstly, we can use the <code>enum rev_sort_order</code> to choose from some
1232 typical orderings.</p></div>
1233 <div class="paragraph"><p><code>topo_order</code> is the same as <code>git log --topo-order</code>: we avoid showing a parent
1234 before all of its children have been shown, and we avoid mixing commits which
1235 are in different lines of history. (<code>git help log</code>'s section on <code>--topo-order</code>
1236 has a very nice diagram to illustrate this.)</p></div>
1237 <div class="paragraph"><p>Let&#8217;s see what happens when we run with <code>REV_SORT_BY_COMMIT_DATE</code> as opposed to
1238 <code>REV_SORT_BY_AUTHOR_DATE</code>. Add the following:</p></div>
1239 <div class="listingblock">
1240 <div class="content">
1241 <pre><code>static void final_rev_info_setup(int argc, const char **argv,
1242                 const char *prefix, struct rev_info *rev)
1243 {
1244         ...
1245
1246         rev-&gt;topo_order = 1;
1247         rev-&gt;sort_order = REV_SORT_BY_COMMIT_DATE;
1248
1249         ...
1250 }</code></pre>
1251 </div></div>
1252 <div class="paragraph"><p>Let&#8217;s output this into a file so we can easily diff it with the walk sorted by
1253 author date.</p></div>
1254 <div class="listingblock">
1255 <div class="content">
1256 <pre><code>$ make
1257 $ ./bin-wrappers/git walken &gt; commit-date.txt</code></pre>
1258 </div></div>
1259 <div class="paragraph"><p>Then, let&#8217;s sort by author date and run it again.</p></div>
1260 <div class="listingblock">
1261 <div class="content">
1262 <pre><code>static void final_rev_info_setup(int argc, const char **argv,
1263                 const char *prefix, struct rev_info *rev)
1264 {
1265         ...
1266
1267         rev-&gt;topo_order = 1;
1268         rev-&gt;sort_order = REV_SORT_BY_AUTHOR_DATE;
1269
1270         ...
1271 }</code></pre>
1272 </div></div>
1273 <div class="listingblock">
1274 <div class="content">
1275 <pre><code>$ make
1276 $ ./bin-wrappers/git walken &gt; author-date.txt</code></pre>
1277 </div></div>
1278 <div class="paragraph"><p>Finally, compare the two. This is a little less helpful without object names or
1279 dates, but hopefully we get the idea.</p></div>
1280 <div class="listingblock">
1281 <div class="content">
1282 <pre><code>$ diff -u commit-date.txt author-date.txt</code></pre>
1283 </div></div>
1284 <div class="paragraph"><p>This display indicates that commits can be reordered after they&#8217;re written, for
1285 example with <code>git rebase</code>.</p></div>
1286 <div class="paragraph"><p>Let&#8217;s try one more reordering of commits. <code>rev_info</code> exposes a <code>reverse</code> flag.
1287 Set that flag somewhere inside of <code>final_rev_info_setup()</code>:</p></div>
1288 <div class="listingblock">
1289 <div class="content">
1290 <pre><code>static void final_rev_info_setup(int argc, const char **argv, const char *prefix,
1291                 struct rev_info *rev)
1292 {
1293         ...
1294
1295         rev-&gt;reverse = 1;
1296
1297         ...
1298 }</code></pre>
1299 </div></div>
1300 <div class="paragraph"><p>Run your walk again and note the difference in order. (If you remove the grep
1301 pattern, you should see the last commit this call gives you as your current
1302 HEAD.)</p></div>
1303 </div>
1304 </div>
1305 </div>
1306 <div class="sect1">
1307 <h2 id="_basic_object_walk">Basic Object Walk</h2>
1308 <div class="sectionbody">
1309 <div class="paragraph"><p>So far we&#8217;ve been walking only commits. But Git has more types of objects than
1310 that! Let&#8217;s see if we can walk <em>all</em> objects, and find out some information
1311 about each one.</p></div>
1312 <div class="paragraph"><p>We can base our work on an example. <code>git pack-objects</code> prepares all kinds of
1313 objects for packing into a bitmap or packfile. The work we are interested in
1314 resides in <code>builtins/pack-objects.c:get_object_list()</code>; examination of that
1315 function shows that the all-object walk is being performed by
1316 <code>traverse_commit_list()</code> or <code>traverse_commit_list_filtered()</code>. Those two
1317 functions reside in <code>list-objects.c</code>; examining the source shows that, despite
1318 the name, these functions traverse all kinds of objects. Let&#8217;s have a look at
1319 the arguments to <code>traverse_commit_list()</code>.</p></div>
1320 <div class="ulist"><ul>
1321 <li>
1322 <p>
1323 <code>struct rev_info *revs</code>: This is the <code>rev_info</code> used for the walk. If
1324   its <code>filter</code> member is not <code>NULL</code>, then <code>filter</code> contains information for
1325   how to filter the object list.
1326 </p>
1327 </li>
1328 <li>
1329 <p>
1330 <code>show_commit_fn show_commit</code>: A callback which will be used to handle each
1331   individual commit object.
1332 </p>
1333 </li>
1334 <li>
1335 <p>
1336 <code>show_object_fn show_object</code>: A callback which will be used to handle each
1337   non-commit object (so each blob, tree, or tag).
1338 </p>
1339 </li>
1340 <li>
1341 <p>
1342 <code>void *show_data</code>: A context buffer which is passed in turn to <code>show_commit</code>
1343   and <code>show_object</code>.
1344 </p>
1345 </li>
1346 </ul></div>
1347 <div class="paragraph"><p>In addition, <code>traverse_commit_list_filtered()</code> has an additional parameter:</p></div>
1348 <div class="ulist"><ul>
1349 <li>
1350 <p>
1351 <code>struct oidset *omitted</code>: A linked-list of object IDs which the provided
1352   filter caused to be omitted.
1353 </p>
1354 </li>
1355 </ul></div>
1356 <div class="paragraph"><p>It looks like these methods use callbacks we provide instead of needing us
1357 to call it repeatedly ourselves. Cool! Let&#8217;s add the callbacks first.</p></div>
1358 <div class="paragraph"><p>For the sake of this tutorial, we&#8217;ll simply keep track of how many of each kind
1359 of object we find. At file scope in <code>builtin/walken.c</code> add the following
1360 tracking variables:</p></div>
1361 <div class="listingblock">
1362 <div class="content">
1363 <pre><code>static int commit_count;
1364 static int tag_count;
1365 static int blob_count;
1366 static int tree_count;</code></pre>
1367 </div></div>
1368 <div class="paragraph"><p>Commits are handled by a different callback than other objects; let&#8217;s do that
1369 one first:</p></div>
1370 <div class="listingblock">
1371 <div class="content">
1372 <pre><code>static void walken_show_commit(struct commit *cmt, void *buf)
1373 {
1374         commit_count++;
1375 }</code></pre>
1376 </div></div>
1377 <div class="paragraph"><p>The <code>cmt</code> argument is fairly self-explanatory. But it&#8217;s worth mentioning that
1378 the <code>buf</code> argument is actually the context buffer that we can provide to the
1379 traversal calls - <code>show_data</code>, which we mentioned a moment ago.</p></div>
1380 <div class="paragraph"><p>Since we have the <code>struct commit</code> object, we can look at all the same parts that
1381 we looked at in our earlier commit-only walk. For the sake of this tutorial,
1382 though, we&#8217;ll just increment the commit counter and move on.</p></div>
1383 <div class="paragraph"><p>The callback for non-commits is a little different, as we&#8217;ll need to check
1384 which kind of object we&#8217;re dealing with:</p></div>
1385 <div class="listingblock">
1386 <div class="content">
1387 <pre><code>static void walken_show_object(struct object *obj, const char *str, void *buf)
1388 {
1389         switch (obj-&gt;type) {
1390         case OBJ_TREE:
1391                 tree_count++;
1392                 break;
1393         case OBJ_BLOB:
1394                 blob_count++;
1395                 break;
1396         case OBJ_TAG:
1397                 tag_count++;
1398                 break;
1399         case OBJ_COMMIT:
1400                 BUG("unexpected commit object in walken_show_object\n");
1401         default:
1402                 BUG("unexpected object type %s in walken_show_object\n",
1403                         type_name(obj-&gt;type));
1404         }
1405 }</code></pre>
1406 </div></div>
1407 <div class="paragraph"><p>Again, <code>obj</code> is fairly self-explanatory, and we can guess that <code>buf</code> is the same
1408 context pointer that <code>walken_show_commit()</code> receives: the <code>show_data</code> argument
1409 to <code>traverse_commit_list()</code> and <code>traverse_commit_list_filtered()</code>. Finally,
1410 <code>str</code> contains the name of the object, which ends up being something like
1411 <code>foo.txt</code> (blob), <code>bar/baz</code> (tree), or <code>v1.2.3</code> (tag).</p></div>
1412 <div class="paragraph"><p>To help assure us that we aren&#8217;t double-counting commits, we&#8217;ll include some
1413 complaining if a commit object is routed through our non-commit callback; we&#8217;ll
1414 also complain if we see an invalid object type. Since those two cases should be
1415 unreachable, and would only change in the event of a semantic change to the Git
1416 codebase, we complain by using <code>BUG()</code> - which is a signal to a developer that
1417 the change they made caused unintended consequences, and the rest of the
1418 codebase needs to be updated to understand that change. <code>BUG()</code> is not intended
1419 to be seen by the public, so it is not localized.</p></div>
1420 <div class="paragraph"><p>Our main object walk implementation is substantially different from our commit
1421 walk implementation, so let&#8217;s make a new function to perform the object walk. We
1422 can perform setup which is applicable to all objects here, too, to keep separate
1423 from setup which is applicable to commit-only walks.</p></div>
1424 <div class="paragraph"><p>We&#8217;ll start by enabling all types of objects in the <code>struct rev_info</code>.  We&#8217;ll
1425 also turn on <code>tree_blobs_in_commit_order</code>, which means that we will walk a
1426 commit&#8217;s tree and everything it points to immediately after we find each commit,
1427 as opposed to waiting for the end and walking through all trees after the commit
1428 history has been discovered. With the appropriate settings configured, we are
1429 ready to call <code>prepare_revision_walk()</code>.</p></div>
1430 <div class="listingblock">
1431 <div class="content">
1432 <pre><code>static void walken_object_walk(struct rev_info *rev)
1433 {
1434         rev-&gt;tree_objects = 1;
1435         rev-&gt;blob_objects = 1;
1436         rev-&gt;tag_objects = 1;
1437         rev-&gt;tree_blobs_in_commit_order = 1;
1438
1439         if (prepare_revision_walk(rev))
1440                 die(_("revision walk setup failed"));
1441
1442         commit_count = 0;
1443         tag_count = 0;
1444         blob_count = 0;
1445         tree_count = 0;</code></pre>
1446 </div></div>
1447 <div class="paragraph"><p>Let&#8217;s start by calling just the unfiltered walk and reporting our counts.
1448 Complete your implementation of <code>walken_object_walk()</code>.
1449 We&#8217;ll also need to include the <code>list-objects.h</code> header.</p></div>
1450 <div class="listingblock">
1451 <div class="content">
1452 <pre><code>#include "list-objects.h"
1453
1454 ...
1455
1456         traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL);
1457
1458         printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count,
1459                 blob_count, tag_count, tree_count);
1460 }</code></pre>
1461 </div></div>
1462 <div class="admonitionblock">
1463 <table><tr>
1464 <td class="icon">
1465 <div class="title">Note</div>
1466 </td>
1467 <td class="content">This output is intended to be machine-parsed. Therefore, we are not
1468 sending it to <code>trace_printf()</code>, and we are not localizing it - we need scripts
1469 to be able to count on the formatting to be exactly the way it is shown here.
1470 If we were intending this output to be read by humans, we would need to localize
1471 it with <code>_()</code>.</td>
1472 </tr></table>
1473 </div>
1474 <div class="paragraph"><p>Finally, we&#8217;ll ask <code>cmd_walken()</code> to use the object walk instead. Discussing
1475 command line options is out of scope for this tutorial, so we&#8217;ll just hardcode
1476 a branch we can change at compile time. Where you call <code>final_rev_info_setup()</code>
1477 and <code>walken_commit_walk()</code>, instead branch like so:</p></div>
1478 <div class="listingblock">
1479 <div class="content">
1480 <pre><code>        if (1) {
1481                 add_head_to_pending(&amp;rev);
1482                 walken_object_walk(&amp;rev);
1483         } else {
1484                 final_rev_info_setup(argc, argv, prefix, &amp;rev);
1485                 walken_commit_walk(&amp;rev);
1486         }</code></pre>
1487 </div></div>
1488 <div class="admonitionblock">
1489 <table><tr>
1490 <td class="icon">
1491 <div class="title">Note</div>
1492 </td>
1493 <td class="content">For simplicity, we&#8217;ve avoided all the filters and sorts we applied in
1494 <code>final_rev_info_setup()</code> and simply added <code>HEAD</code> to our pending queue. If you
1495 want, you can certainly use the filters we added before by moving
1496 <code>final_rev_info_setup()</code> out of the conditional and removing the call to
1497 <code>add_head_to_pending()</code>.</td>
1498 </tr></table>
1499 </div>
1500 <div class="paragraph"><p>Now we can try to run our command! It should take noticeably longer than the
1501 commit walk, but an examination of the output will give you an idea why. Your
1502 output should look similar to this example, but with different counts:</p></div>
1503 <div class="listingblock">
1504 <div class="content">
1505 <pre><code>Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees.</code></pre>
1506 </div></div>
1507 <div class="paragraph"><p>This makes sense. We have more trees than commits because the Git project has
1508 lots of subdirectories which can change, plus at least one tree per commit. We
1509 have no tags because we started on a commit (<code>HEAD</code>) and while tags can point to
1510 commits, commits can&#8217;t point to tags.</p></div>
1511 <div class="admonitionblock">
1512 <table><tr>
1513 <td class="icon">
1514 <div class="title">Note</div>
1515 </td>
1516 <td class="content">You will have different counts when you run this yourself! The number of
1517 objects grows along with the Git project.</td>
1518 </tr></table>
1519 </div>
1520 <div class="sect2">
1521 <h3 id="_adding_a_filter_2">Adding a Filter</h3>
1522 <div class="paragraph"><p>There are a handful of filters that we can apply to the object walk laid out in
1523 <code>Documentation/rev-list-options.txt</code>. These filters are typically useful for
1524 operations such as creating packfiles or performing a partial clone. They are
1525 defined in <code>list-objects-filter-options.h</code>. For the purposes of this tutorial we
1526 will use the "tree:1" filter, which causes the walk to omit all trees and blobs
1527 which are not directly referenced by commits reachable from the commit in
1528 <code>pending</code> when the walk begins. (<code>pending</code> is the list of objects which need to
1529 be traversed during a walk; you can imagine a breadth-first tree traversal to
1530 help understand. In our case, that means we omit trees and blobs not directly
1531 referenced by <code>HEAD</code> or <code>HEAD</code>'s history, because we begin the walk with only
1532 <code>HEAD</code> in the <code>pending</code> list.)</p></div>
1533 <div class="paragraph"><p>For now, we are not going to track the omitted objects, so we&#8217;ll replace those
1534 parameters with <code>NULL</code>. For the sake of simplicity, we&#8217;ll add a simple
1535 build-time branch to use our filter or not. Preface the line calling
1536 <code>traverse_commit_list()</code> with the following, which will remind us which kind of
1537 walk we&#8217;ve just performed:</p></div>
1538 <div class="listingblock">
1539 <div class="content">
1540 <pre><code>        if (0) {
1541                 /* Unfiltered: */
1542                 trace_printf(_("Unfiltered object walk.\n"));
1543         } else {
1544                 trace_printf(
1545                         _("Filtered object walk with filterspec 'tree:1'.\n"));
1546                 CALLOC_ARRAY(rev-&gt;filter, 1);
1547                 parse_list_objects_filter(rev-&gt;filter, "tree:1");
1548         }
1549         traverse_commit_list(rev, walken_show_commit,
1550                              walken_show_object, NULL);</code></pre>
1551 </div></div>
1552 <div class="paragraph"><p>The <code>rev-&gt;filter</code> member is usually built directly from a command
1553 line argument, so the module provides an easy way to build one from a string.
1554 Even though we aren&#8217;t taking user input right now, we can still build one with
1555 a hardcoded string using <code>parse_list_objects_filter()</code>.</p></div>
1556 <div class="paragraph"><p>With the filter spec "tree:1", we are expecting to see <em>only</em> the root tree for
1557 each commit; therefore, the tree object count should be less than or equal to
1558 the number of commits. (For an example of why that&#8217;s true: <code>git commit --revert</code>
1559 points to the same tree object as its grandparent.)</p></div>
1560 </div>
1561 <div class="sect2">
1562 <h3 id="_counting_omitted_objects">Counting Omitted Objects</h3>
1563 <div class="paragraph"><p>We also have the capability to enumerate all objects which were omitted by a
1564 filter, like with <code>git log --filter=&lt;spec&gt; --filter-print-omitted</code>. Asking
1565 <code>traverse_commit_list_filtered()</code> to populate the <code>omitted</code> list means that our
1566 object walk does not perform any better than an unfiltered object walk; all
1567 reachable objects are walked in order to populate the list.</p></div>
1568 <div class="paragraph"><p>First, add the <code>struct oidset</code> and related items we will use to iterate it:</p></div>
1569 <div class="listingblock">
1570 <div class="content">
1571 <pre><code>static void walken_object_walk(
1572         ...
1573
1574         struct oidset omitted;
1575         struct oidset_iter oit;
1576         struct object_id *oid = NULL;
1577         int omitted_count = 0;
1578         oidset_init(&amp;omitted, 0);
1579
1580         ...</code></pre>
1581 </div></div>
1582 <div class="paragraph"><p>Modify the call to <code>traverse_commit_list_filtered()</code> to include your <code>omitted</code>
1583 object:</p></div>
1584 <div class="listingblock">
1585 <div class="content">
1586 <pre><code>        ...
1587
1588                 traverse_commit_list_filtered(rev,
1589                         walken_show_commit, walken_show_object, NULL, &amp;omitted);
1590
1591         ...</code></pre>
1592 </div></div>
1593 <div class="paragraph"><p>Then, after your traversal, the <code>oidset</code> traversal is pretty straightforward.
1594 Count all the objects within and modify the print statement:</p></div>
1595 <div class="listingblock">
1596 <div class="content">
1597 <pre><code>        /* Count the omitted objects. */
1598         oidset_iter_init(&amp;omitted, &amp;oit);
1599
1600         while ((oid = oidset_iter_next(&amp;oit)))
1601                 omitted_count++;
1602
1603         printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n",
1604                 commit_count, blob_count, tag_count, tree_count, omitted_count);</code></pre>
1605 </div></div>
1606 <div class="paragraph"><p>By running your walk with and without the filter, you should find that the total
1607 object count in each case is identical. You can also time each invocation of
1608 the <code>walken</code> subcommand, with and without <code>omitted</code> being passed in, to confirm
1609 to yourself the runtime impact of tracking all omitted objects.</p></div>
1610 </div>
1611 <div class="sect2">
1612 <h3 id="_changing_the_order_2">Changing the Order</h3>
1613 <div class="paragraph"><p>Finally, let&#8217;s demonstrate that you can also reorder walks of all objects, not
1614 just walks of commits. First, we&#8217;ll make our handlers chattier - modify
1615 <code>walken_show_commit()</code> and <code>walken_show_object()</code> to print the object as they
1616 go:</p></div>
1617 <div class="listingblock">
1618 <div class="content">
1619 <pre><code>static void walken_show_commit(struct commit *cmt, void *buf)
1620 {
1621         trace_printf("commit: %s\n", oid_to_hex(&amp;cmt-&gt;object.oid));
1622         commit_count++;
1623 }
1624
1625 static void walken_show_object(struct object *obj, const char *str, void *buf)
1626 {
1627         trace_printf("%s: %s\n", type_name(obj-&gt;type), oid_to_hex(&amp;obj-&gt;oid));
1628
1629         ...
1630 }</code></pre>
1631 </div></div>
1632 <div class="admonitionblock">
1633 <table><tr>
1634 <td class="icon">
1635 <div class="title">Note</div>
1636 </td>
1637 <td class="content">Since we will be examining this output directly as humans, we&#8217;ll use
1638 <code>trace_printf()</code> here. Additionally, since this change introduces a significant
1639 number of printed lines, using <code>trace_printf()</code> will allow us to easily silence
1640 those lines without having to recompile.</td>
1641 </tr></table>
1642 </div>
1643 <div class="paragraph"><p>(Leave the counter increment logic in place.)</p></div>
1644 <div class="paragraph"><p>With only that change, run again (but save yourself some scrollback):</p></div>
1645 <div class="listingblock">
1646 <div class="content">
1647 <pre><code>$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10</code></pre>
1648 </div></div>
1649 <div class="paragraph"><p>Take a look at the top commit with <code>git show</code> and the object ID you printed; it
1650 should be the same as the output of <code>git show HEAD</code>.</p></div>
1651 <div class="paragraph"><p>Next, let&#8217;s change a setting on our <code>struct rev_info</code> within
1652 <code>walken_object_walk()</code>. Find where you&#8217;re changing the other settings on <code>rev</code>,
1653 such as <code>rev-&gt;tree_objects</code> and <code>rev-&gt;tree_blobs_in_commit_order</code>, and add the
1654 <code>reverse</code> setting at the bottom:</p></div>
1655 <div class="listingblock">
1656 <div class="content">
1657 <pre><code>        ...
1658
1659         rev-&gt;tree_objects = 1;
1660         rev-&gt;blob_objects = 1;
1661         rev-&gt;tag_objects = 1;
1662         rev-&gt;tree_blobs_in_commit_order = 1;
1663         rev-&gt;reverse = 1;
1664
1665         ...</code></pre>
1666 </div></div>
1667 <div class="paragraph"><p>Now, run again, but this time, let&#8217;s grab the last handful of objects instead
1668 of the first handful:</p></div>
1669 <div class="listingblock">
1670 <div class="content">
1671 <pre><code>$ make
1672 $ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10</code></pre>
1673 </div></div>
1674 <div class="paragraph"><p>The last commit object given should have the same OID as the one we saw at the
1675 top before, and running <code>git show &lt;oid&gt;</code> with that OID should give you again
1676 the same results as <code>git show HEAD</code>. Furthermore, if you run and examine the
1677 first ten lines again (with <code>head</code> instead of <code>tail</code> like we did before applying
1678 the <code>reverse</code> setting), you should see that now the first commit printed is the
1679 initial commit, <code>e83c5163</code>.</p></div>
1680 </div>
1681 </div>
1682 </div>
1683 <div class="sect1">
1684 <h2 id="_wrapping_up">Wrapping Up</h2>
1685 <div class="sectionbody">
1686 <div class="paragraph"><p>Let&#8217;s review. In this tutorial, we:</p></div>
1687 <div class="ulist"><ul>
1688 <li>
1689 <p>
1690 Built a commit walk from the ground up
1691 </p>
1692 </li>
1693 <li>
1694 <p>
1695 Enabled a grep filter for that commit walk
1696 </p>
1697 </li>
1698 <li>
1699 <p>
1700 Changed the sort order of that filtered commit walk
1701 </p>
1702 </li>
1703 <li>
1704 <p>
1705 Built an object walk (tags, commits, trees, and blobs) from the ground up
1706 </p>
1707 </li>
1708 <li>
1709 <p>
1710 Learned how to add a filter-spec to an object walk
1711 </p>
1712 </li>
1713 <li>
1714 <p>
1715 Changed the display order of the filtered object walk
1716 </p>
1717 </li>
1718 </ul></div>
1719 </div>
1720 </div>
1721 </div>
1722 <div id="footnotes"><hr /></div>
1723 <div id="footer">
1724 <div id="footer-text">
1725 Last updated
1726  2022-09-21 15:44:34 PDT
1727 </div>
1728 </div>
1729 </body>
1730 </html>