[thirdparty/git.git] / Documentation / technical / api-tree-walking.txt

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.

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().

`strbuf_make_traverse_path`::

	Convenience wrapper to `make_traverse_path` into a strbuf.

Authors
-------

Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds
<torvalds@linux-foundation.org>
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
6639ffc2 SB	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.
e6c111b4 MM	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
5c377d3d RS	58	Initialize a `tree_desc` and decode its first entry given the
	59	object ID of a tree. Returns the `buffer` member if the latter
	60	is a valid tree identifier and NULL otherwise.
6639ffc2 SB	61
	62	`setup_traverse_info`::
	63
	64	Initialize a `traverse_info` given the pathname of the tree to start
947208b7	65	traversing from.
6639ffc2 SB	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
c43ab062 JK	141	`strbuf_make_traverse_path`::
	142
	143	Convenience wrapper to `make_traverse_path` into a strbuf.
	144
6639ffc2 SB	145	Authors
	146	-------
	147
	148	Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds
	149	<torvalds@linux-foundation.org>