technical-docs: document tree-walking API
Signed-off-by: Stephen Boyd <bebarino@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Stephen Boyd committed
Aug 3, 2009 at 21:13 UTC
6639ffc2e026b34b906854b8c60bd72d4b95e78d
1 file changed
+140
-7
Documentation/technical/api-tree-walking.txt
+140
-7
@@ -1,12 +1,145 @@
1
tree walking API
2
================
3
4
-Talk about <tree-walk.h>, things like
4
+The tree walking API is used to traverse and inspect trees.
5
6
-* struct tree_desc
7
-* init_tree_desc
8
-* tree_entry_extract
9
-* update_tree_entry
10
-* get_tree_entry
6
+Data Structures
7
+---------------
8
12
-(JC, Linus)
9
+`struct name_entry`::
10
+
11
+ An entry in a tree. Each entry has a sha1 identifier, pathname, and
12
+ mode.
13
+
14
+`struct tree_desc`::
15
+
16
+ A semi-opaque data structure used to maintain the current state of the
17
+ walk.
18
++
19
+* `buffer` is a pointer into the memory representation of the tree. It always
20
+points at the current entry being visited.
21
+
22
+* `size` counts the number of bytes left in the `buffer`.
23
+
24
+* `entry` points to the current entry being visited.
25
+
26
+`struct traverse_info`::
27
+
28
+ A structure used to maintain the state of a traversal.
29
++
30
+* `prev` points to the traverse_info which was used to descend into the
31
+current tree. If this is the top-level tree `prev` will point to
32
+a dummy traverse_info.
33
+
34
+* `name` is the entry for the current tree (if the tree is a subtree).
35
+
36
+* `pathlen` is the length of the full path for the current tree.
37
+
38
+* `conflicts` can be used by callbacks to maintain directory-file conflicts.
39
+
40
+* `fn` is a callback called for each entry in the tree. See Traversing for more
41
+information.
42
+
43
+* `data` can be anything the `fn` callback would want to use.
44
+
45
+Initializing
46
+------------
47
+
48
+`init_tree_desc`::
49
+
50
+ Initialize a `tree_desc` and decode its first entry. The buffer and
51
+ size parameters are assumed to be the same as the buffer and size
52
+ members of `struct tree`.
53
+
54
+`fill_tree_descriptor`::
55
+
56
+ Initialize a `tree_desc` and decode its first entry given the sha1 of
57
+ a tree. Returns the `buffer` member if the sha1 is a valid tree
58
+ identifier and NULL otherwise.
59
+
60
+`setup_traverse_info`::
61
+
62
+ Initialize a `traverse_info` given the pathname of the tree to start
63
+ traversing from. The `base` argument is assumed to be the `path`
64
+ member of the `name_entry` being recursed into unless the tree is a
65
+ top-level tree in which case the empty string ("") is used.
66
+
67
+Walking
68
+-------
69
+
70
+`tree_entry`::
71
+
72
+ Visit the next entry in a tree. Returns 1 when there are more entries
73
+ left to visit and 0 when all entries have been visited. This is
74
+ commonly used in the test of a while loop.
75
+
76
+`tree_entry_len`::
77
+
78
+ Calculate the length of a tree entry's pathname. This utilizes the
79
+ memory structure of a tree entry to avoid the overhead of using a
80
+ generic strlen().
81
+
82
+`update_tree_entry`::
83
+
84
+ Walk to the next entry in a tree. This is commonly used in conjunction
85
+ with `tree_entry_extract` to inspect the current entry.
86
+
87
+`tree_entry_extract`::
88
+
89
+ Decode the entry currently being visited (the one pointed to by
90
+ `tree_desc's` `entry` member) and return the sha1 of the entry. The
91
+ `pathp` and `modep` arguments are set to the entry's pathname and mode
92
+ respectively.
93
+
94
+`get_tree_entry`::
95
+
96
+ Find an entry in a tree given a pathname and the sha1 of a tree to
97
+ search. Returns 0 if the entry is found and -1 otherwise. The third
98
+ and fourth parameters are set to the entry's sha1 and mode
99
+ respectively.
100
+
101
+Traversing
102
+----------
103
+
104
+`traverse_trees`::
105
+
106
+ Traverse `n` number of trees in parallel. The `fn` callback member of
107
+ `traverse_info` is called once for each tree entry.
108
+
109
+`traverse_callback_t`::
110
+ The arguments passed to the traverse callback are as follows:
111
++
112
+* `n` counts the number of trees being traversed.
113
+
114
+* `mask` has its nth bit set if something exists in the nth entry.
115
+
116
+* `dirmask` has its nth bit set if the nth tree's entry is a directory.
117
+
118
+* `entry` is an array of size `n` where the nth entry is from the nth tree.
119
+
120
+* `info` maintains the state of the traversal.
121
+
122
++
123
+Returning a negative value will terminate the traversal. Otherwise the
124
+return value is treated as an update mask. If the nth bit is set the nth tree
125
+will be updated and if the bit is not set the nth tree entry will be the
126
+same in the next callback invocation.
127
+
128
+`make_traverse_path`::
129
+
130
+ Generate the full pathname of a tree entry based from the root of the
131
+ traversal. For example, if the traversal has recursed into another
132
+ tree named "bar" the pathname of an entry "baz" in the "bar"
133
+ tree would be "bar/baz".
134
+
135
+`traverse_path_len`::
136
+
137
+ Calculate the length of a pathname returned by `make_traverse_path`.
138
+ This utilizes the memory structure of a tree entry to avoid the
139
+ overhead of using a generic strlen().
140
+
141
+Authors
142
+-------
143
+
144
+Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds
145
+<torvalds@linux-foundation.org>