Commit | Line | Data |
---|---|---|
530e741c JH |
1 | tree walking API |
2 | ================ | |
3 | ||
6639ffc2 | 4 | The tree walking API is used to traverse and inspect trees. |
530e741c | 5 | |
6639ffc2 SB |
6 | Data Structures |
7 | --------------- | |
530e741c | 8 | |
6639ffc2 SB |
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 | ||
e6c111b4 MM |
45 | * `show_all_errors` tells whether to stop at the first error or not. |
46 | ||
6639ffc2 SB |
47 | Initializing |
48 | ------------ | |
49 | ||
50 | `init_tree_desc`:: | |
51 | ||
52 | Initialize a `tree_desc` and decode its first entry. The buffer and | |
53 | size parameters are assumed to be the same as the buffer and size | |
54 | members of `struct tree`. | |
55 | ||
56 | `fill_tree_descriptor`:: | |
57 | ||
58 | Initialize a `tree_desc` and decode its first entry given the sha1 of | |
59 | a tree. Returns the `buffer` member if the sha1 is a valid tree | |
60 | identifier and NULL otherwise. | |
61 | ||
62 | `setup_traverse_info`:: | |
63 | ||
64 | Initialize a `traverse_info` given the pathname of the tree to start | |
65 | traversing from. The `base` argument is assumed to be the `path` | |
66 | member of the `name_entry` being recursed into unless the tree is a | |
67 | top-level tree in which case the empty string ("") is used. | |
68 | ||
69 | Walking | |
70 | ------- | |
71 | ||
72 | `tree_entry`:: | |
73 | ||
74 | Visit the next entry in a tree. Returns 1 when there are more entries | |
75 | left to visit and 0 when all entries have been visited. This is | |
76 | commonly used in the test of a while loop. | |
77 | ||
78 | `tree_entry_len`:: | |
79 | ||
80 | Calculate the length of a tree entry's pathname. This utilizes the | |
81 | memory structure of a tree entry to avoid the overhead of using a | |
82 | generic strlen(). | |
83 | ||
84 | `update_tree_entry`:: | |
85 | ||
86 | Walk to the next entry in a tree. This is commonly used in conjunction | |
87 | with `tree_entry_extract` to inspect the current entry. | |
88 | ||
89 | `tree_entry_extract`:: | |
90 | ||
91 | Decode the entry currently being visited (the one pointed to by | |
92 | `tree_desc's` `entry` member) and return the sha1 of the entry. The | |
93 | `pathp` and `modep` arguments are set to the entry's pathname and mode | |
94 | respectively. | |
95 | ||
96 | `get_tree_entry`:: | |
97 | ||
98 | Find an entry in a tree given a pathname and the sha1 of a tree to | |
99 | search. Returns 0 if the entry is found and -1 otherwise. The third | |
100 | and fourth parameters are set to the entry's sha1 and mode | |
101 | respectively. | |
102 | ||
103 | Traversing | |
104 | ---------- | |
105 | ||
106 | `traverse_trees`:: | |
107 | ||
108 | Traverse `n` number of trees in parallel. The `fn` callback member of | |
109 | `traverse_info` is called once for each tree entry. | |
110 | ||
111 | `traverse_callback_t`:: | |
112 | The arguments passed to the traverse callback are as follows: | |
113 | + | |
114 | * `n` counts the number of trees being traversed. | |
115 | ||
116 | * `mask` has its nth bit set if something exists in the nth entry. | |
117 | ||
118 | * `dirmask` has its nth bit set if the nth tree's entry is a directory. | |
119 | ||
120 | * `entry` is an array of size `n` where the nth entry is from the nth tree. | |
121 | ||
122 | * `info` maintains the state of the traversal. | |
123 | ||
124 | + | |
125 | Returning a negative value will terminate the traversal. Otherwise the | |
126 | return value is treated as an update mask. If the nth bit is set the nth tree | |
127 | will be updated and if the bit is not set the nth tree entry will be the | |
128 | same in the next callback invocation. | |
129 | ||
130 | `make_traverse_path`:: | |
131 | ||
132 | Generate the full pathname of a tree entry based from the root of the | |
133 | traversal. For example, if the traversal has recursed into another | |
134 | tree named "bar" the pathname of an entry "baz" in the "bar" | |
135 | tree would be "bar/baz". | |
136 | ||
137 | `traverse_path_len`:: | |
138 | ||
139 | Calculate the length of a pathname returned by `make_traverse_path`. | |
140 | This utilizes the memory structure of a tree entry to avoid the | |
141 | overhead of using a generic strlen(). | |
142 | ||
143 | Authors | |
144 | ------- | |
145 | ||
146 | Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds | |
147 | <torvalds@linux-foundation.org> |