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">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.4.5" />
7 <title>tree walking API
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
245 list-style-type: upper-roman
;
248 div
.compact ul
, div
.compact ol
,
249 div
.compact p
, div
.compact p
,
250 div
.compact div
, div
.compact div
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
275 div
.tableblock
> table
[frame
="hsides"] {
276 border-left-style: none
;
277 border-right-style: none
;
279 div
.tableblock
> table
[frame
="vsides"] {
280 border-top-style: none
;
281 border-bottom-style: none
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Workarounds for IE6's broken and incomplete CSS2. */
344 div
.sidebar-content
{
346 border: 1px solid silver
;
349 div
.sidebar-title
, div
.image-title
{
351 font-family: sans-serif
;
354 margin-bottom: 0.5em;
357 div
.listingblock div
.content
{
358 border: 1px solid silver
;
363 div
.quoteblock-attribution
{
368 div
.verseblock-content
{
371 div
.verseblock-attribution
{
376 div
.exampleblock-content
{
377 border-left: 2px solid silver
;
381 /* IE6 sets dynamically generated links as visited. */
382 div#toc
a:visited
{ color: blue
; }
387 <h1>tree walking API
</h1>
390 <div class=
"sectionbody">
391 <div class=
"paragraph"><p>The tree walking API is used to traverse and inspect trees.
</p></div>
394 <h2 id=
"_data_structures">Data Structures
</h2>
395 <div class=
"sectionbody">
396 <div class=
"dlist"><dl>
398 <tt>struct name_entry
</tt>
402 An entry in a tree. Each entry has a sha1 identifier, pathname, and
407 <tt>struct tree_desc
</tt>
411 A semi-opaque data structure used to maintain the current state of the
414 <div class=
"ulist"><ul>
417 <tt>buffer
</tt> is a pointer into the memory representation of the tree. It always
418 points at the current entry being visited.
423 <tt>size
</tt> counts the number of bytes left in the
<tt>buffer
</tt>.
428 <tt>entry
</tt> points to the current entry being visited.
434 <tt>struct traverse_info
</tt>
438 A structure used to maintain the state of a traversal.
440 <div class=
"ulist"><ul>
443 <tt>prev
</tt> points to the traverse_info which was used to descend into the
444 current tree. If this is the top-level tree
<tt>prev
</tt> will point to
445 a dummy traverse_info.
450 <tt>name
</tt> is the entry for the current tree (if the tree is a subtree).
455 <tt>pathlen
</tt> is the length of the full path for the current tree.
460 <tt>conflicts
</tt> can be used by callbacks to maintain directory-file conflicts.
465 <tt>fn
</tt> is a callback called for each entry in the tree. See Traversing for more
471 <tt>data
</tt> can be anything the
<tt>fn
</tt> callback would want to use.
476 <tt>show_all_errors
</tt> tells whether to stop at the first error or not.
483 <h2 id=
"_initializing">Initializing
</h2>
484 <div class=
"sectionbody">
485 <div class=
"dlist"><dl>
487 <tt>init_tree_desc
</tt>
491 Initialize a
<tt>tree_desc
</tt> and decode its first entry. The buffer and
492 size parameters are assumed to be the same as the buffer and size
493 members of
<tt>struct tree
</tt>.
497 <tt>fill_tree_descriptor
</tt>
501 Initialize a
<tt>tree_desc
</tt> and decode its first entry given the sha1 of
502 a tree. Returns the
<tt>buffer
</tt> member if the sha1 is a valid tree
503 identifier and NULL otherwise.
507 <tt>setup_traverse_info
</tt>
511 Initialize a
<tt>traverse_info
</tt> given the pathname of the tree to start
512 traversing from. The
<tt>base
</tt> argument is assumed to be the
<tt>path
</tt>
513 member of the
<tt>name_entry
</tt> being recursed into unless the tree is a
514 top-level tree in which case the empty string (
"") is used.
519 <h2 id=
"_walking">Walking
</h2>
520 <div class=
"sectionbody">
521 <div class=
"dlist"><dl>
527 Visit the next entry in a tree. Returns
1 when there are more entries
528 left to visit and
0 when all entries have been visited. This is
529 commonly used in the test of a while loop.
533 <tt>tree_entry_len
</tt>
537 Calculate the length of a tree entry
’s pathname. This utilizes the
538 memory structure of a tree entry to avoid the overhead of using a
543 <tt>update_tree_entry
</tt>
547 Walk to the next entry in a tree. This is commonly used in conjunction
548 with
<tt>tree_entry_extract
</tt> to inspect the current entry.
552 <tt>tree_entry_extract
</tt>
556 Decode the entry currently being visited (the one pointed to by
557 <tt>tree_desc
’s
</tt> <tt>entry
</tt> member) and return the sha1 of the entry. The
558 <tt>pathp
</tt> and
<tt>modep
</tt> arguments are set to the entry
’s pathname and mode
563 <tt>get_tree_entry
</tt>
567 Find an entry in a tree given a pathname and the sha1 of a tree to
568 search. Returns
0 if the entry is found and -
1 otherwise. The third
569 and fourth parameters are set to the entry
’s sha1 and mode
575 <h2 id=
"_traversing">Traversing
</h2>
576 <div class=
"sectionbody">
577 <div class=
"dlist"><dl>
579 <tt>traverse_trees
</tt>
583 Traverse
<tt>n
</tt> number of trees in parallel. The
<tt>fn
</tt> callback member of
584 <tt>traverse_info
</tt> is called once for each tree entry.
588 <tt>traverse_callback_t
</tt>
592 The arguments passed to the traverse callback are as follows:
594 <div class=
"ulist"><ul>
597 <tt>n
</tt> counts the number of trees being traversed.
602 <tt>mask
</tt> has its nth bit set if something exists in the nth entry.
607 <tt>dirmask
</tt> has its nth bit set if the nth tree
’s entry is a directory.
612 <tt>entry
</tt> is an array of size
<tt>n
</tt> where the nth entry is from the nth tree.
617 <tt>info
</tt> maintains the state of the traversal.
621 <div class=
"paragraph"><p>Returning a negative value will terminate the traversal. Otherwise the
622 return value is treated as an update mask. If the nth bit is set the nth tree
623 will be updated and if the bit is not set the nth tree entry will be the
624 same in the next callback invocation.
</p></div>
627 <tt>make_traverse_path
</tt>
631 Generate the full pathname of a tree entry based from the root of the
632 traversal. For example, if the traversal has recursed into another
633 tree named
"bar" the pathname of an entry
"baz" in the
"bar"
634 tree would be
"bar/baz".
638 <tt>traverse_path_len
</tt>
642 Calculate the length of a pathname returned by
<tt>make_traverse_path
</tt>.
643 This utilizes the memory structure of a tree entry to avoid the
644 overhead of using a generic strlen().
649 <h2 id=
"_authors">Authors
</h2>
650 <div class=
"sectionbody">
651 <div class=
"paragraph"><p>Written by Junio C Hamano
<<a href=
"mailto:gitster@pobox.com">gitster@pobox.com
</a>> and Linus Torvalds
652 <<a href=
"mailto:torvalds@linux-foundation.org">torvalds@linux-foundation.org
</a>></p></div>
655 <div id=
"footer-text">
656 Last updated
2010-
08-
22 07:
24:
51 UTC