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 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 <[email protected]> and Linus Torvalds <[email protected]>