You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
145 lines
4.2 KiB
145 lines
4.2 KiB
tree walking API |
|
================ |
|
|
|
The tree walking API is used to traverse and inspect trees. |
|
|
|
Data Structures |
|
--------------- |
|
|
|
`struct name_entry`:: |
|
|
|
An entry in a tree. Each entry has a sha1 identifier, pathname, and |
|
mode. |
|
|
|
`struct tree_desc`:: |
|
|
|
A semi-opaque data structure used to maintain the current state of the |
|
walk. |
|
+ |
|
* `buffer` is a pointer into the memory representation of the tree. It always |
|
points at the current entry being visited. |
|
|
|
* `size` counts the number of bytes left in the `buffer`. |
|
|
|
* `entry` points to the current entry being visited. |
|
|
|
`struct traverse_info`:: |
|
|
|
A structure used to maintain the state of a traversal. |
|
+ |
|
* `prev` points to the traverse_info which was used to descend into the |
|
current tree. If this is the top-level tree `prev` will point to |
|
a dummy traverse_info. |
|
|
|
* `name` is the entry for the current tree (if the tree is a subtree). |
|
|
|
* `pathlen` is the length of the full path for the current tree. |
|
|
|
* `conflicts` can be used by callbacks to maintain directory-file conflicts. |
|
|
|
* `fn` is a callback called for each entry in the tree. See Traversing for more |
|
information. |
|
|
|
* `data` can be anything the `fn` callback would want to use. |
|
|
|
Initializing |
|
------------ |
|
|
|
`init_tree_desc`:: |
|
|
|
Initialize a `tree_desc` and decode its first entry. The buffer and |
|
size parameters are assumed to be the same as the buffer and size |
|
members of `struct tree`. |
|
|
|
`fill_tree_descriptor`:: |
|
|
|
Initialize a `tree_desc` and decode its first entry given the sha1 of |
|
a tree. Returns the `buffer` member if the sha1 is a valid tree |
|
identifier and NULL otherwise. |
|
|
|
`setup_traverse_info`:: |
|
|
|
Initialize a `traverse_info` given the pathname of the tree to start |
|
traversing from. The `base` argument is assumed to be the `path` |
|
member of the `name_entry` being recursed into unless the tree is a |
|
top-level tree in which case the empty string ("") is used. |
|
|
|
Walking |
|
------- |
|
|
|
`tree_entry`:: |
|
|
|
Visit the next entry in a tree. Returns 1 when there are more entries |
|
left to visit and 0 when all entries have been visited. This is |
|
commonly used in the test of a while loop. |
|
|
|
`tree_entry_len`:: |
|
|
|
Calculate the length of a tree entry's pathname. This utilizes the |
|
memory structure of a tree entry to avoid the overhead of using a |
|
generic strlen(). |
|
|
|
`update_tree_entry`:: |
|
|
|
Walk to the next entry in a tree. This is commonly used in conjunction |
|
with `tree_entry_extract` to inspect the current entry. |
|
|
|
`tree_entry_extract`:: |
|
|
|
Decode the entry currently being visited (the one pointed to by |
|
`tree_desc's` `entry` member) and return the sha1 of the entry. The |
|
`pathp` and `modep` arguments are set to the entry's pathname and mode |
|
respectively. |
|
|
|
`get_tree_entry`:: |
|
|
|
Find an entry in a tree given a pathname and the sha1 of a tree to |
|
search. Returns 0 if the entry is found and -1 otherwise. The third |
|
and fourth parameters are set to the entry's sha1 and mode |
|
respectively. |
|
|
|
Traversing |
|
---------- |
|
|
|
`traverse_trees`:: |
|
|
|
Traverse `n` number of trees in parallel. The `fn` callback member of |
|
`traverse_info` is called once for each tree entry. |
|
|
|
`traverse_callback_t`:: |
|
The arguments passed to the traverse callback are as follows: |
|
+ |
|
* `n` counts the number of trees being traversed. |
|
|
|
* `mask` has its nth bit set if something exists in the nth entry. |
|
|
|
* `dirmask` has its nth bit set if the nth tree's entry is a directory. |
|
|
|
* `entry` is an array of size `n` where the nth entry is from the nth tree. |
|
|
|
* `info` maintains the state of the traversal. |
|
|
|
+ |
|
Returning a negative value will terminate the traversal. Otherwise the |
|
return value is treated as an update mask. If the nth bit is set the nth tree |
|
will be updated and if the bit is not set the nth tree entry will be the |
|
same in the next callback invocation. |
|
|
|
`make_traverse_path`:: |
|
|
|
Generate the full pathname of a tree entry based from the root of the |
|
traversal. For example, if the traversal has recursed into another |
|
tree named "bar" the pathname of an entry "baz" in the "bar" |
|
tree would be "bar/baz". |
|
|
|
`traverse_path_len`:: |
|
|
|
Calculate the length of a pathname returned by `make_traverse_path`. |
|
This utilizes the memory structure of a tree entry to avoid the |
|
overhead of using a generic strlen(). |
|
|
|
Authors |
|
------- |
|
|
|
Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds |
|
<torvalds@linux-foundation.org>
|
|
|