| 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. |
| |
| * `show_all_errors` tells whether to stop at the first error or not. |
| |
| 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 |
| object ID of a tree. Returns the `buffer` member if the latter |
| 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> |