{"thread":{"id":"20270","subject":"[RFC/PATCH] technical-docs: document tree-walking API","startedAt":"2009-07-29T05:23:15Z","lastAt":"2009-07-29T08:25:05Z","messageCount":2,"participants":["Stephen Boyd","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"119015","messageId":"1248844995-13769-1-git-send-email-bebarino@gmail.com","threadId":"20270","inReplyTo":null,"subject":"[RFC/PATCH] technical-docs: document tree-walking API","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-07-29T05:23:15Z","receivedAt":"2009-07-29T05:23:15Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"---\n\nSince it's rc time right now I've decided to look into documenting one of the\nsimpler API's, or so I thought ;-) This is my first attempt and I would\nappreciate any and all feedback.\n\nSome things to get you started:\n\n        - the traversal callback mask parameter\n\t- a better general usage description at the top\n\t- add an authors section?\n\n Documentation/technical/api-tree-walking.txt |  142 ++++++++++++++++++++++++-\n 1 files changed, 136 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt\nindex e3ddf91..baa382d 100644\n--- a/Documentation/technical/api-tree-walking.txt\n+++ b/Documentation/technical/api-tree-walking.txt\n@@ -1,12 +1,142 @@\n tree walking API\n ================\n \n-Talk about <tree-walk.h>, things like\n+The tree walking API is used to traverse and inspect trees.\n \n-* struct tree_desc\n-* init_tree_desc\n-* tree_entry_extract\n-* update_tree_entry\n-* get_tree_entry\n+Data Structures\n+---------------\n+\n+`struct name_entry`::\n+\n+\tAn entry in a tree. Each entry has a sha1 identifier, pathname, and\n+\tmode.\n+\n+`struct tree_desc`::\n+\n+\tA semi-opaque data structure used to maintain the current state of the\n+\twalk. \n++\n+* `buffer` is a pointer into the memory representation of the tree. It always\n+points at the current entry being visited.\n+\n+* `size` counts the number of bytes left in the `buffer`.\n+\n+* `entry` points to the current entry being visited.\n+\n+`struct traverse_info`::\n+\n+\tA structure used to maintain the state of a traversal. The members are\n+\tas follows\n++\n+* `prev` points to the traverse_info which was used to descend into the\n+current tree. If this is the top-level tree `prev` will point to\n+a dummy traverse_info. \n+\n+* `name` is the entry for the current tree (if the tree is a subtree).\n+\n+* `pathlen` is the length of the full path for the current tree.\n+\n+* `conflicts` can be used by callbacks to maintain directory-file conflicts.\n+\n+* `fn` is a callback called for each entry in the tree. See Traversing for more\n+information.\n+\n+* `data` can be anything the `fn` callback would want to use.\n+\n+Initializing\n+------------\n+\n+`init_tree_desc`::\n+\n+\tInitialize a `tree_desc` and decode its first entry. The buffer and\n+\tsize parameters are assumed to be the same as the buffer and size\n+\tmembers of `struct tree`.\n+\n+`fill_tree_descriptor`::\n+\n+\tInitialize a `tree_desc` and decode its first entry given the sha1 of\n+\ta tree. Returns the `buffer` member if the sha1 is a valid tree\n+\tidentifier and NULL otherwise.\n+\n+`setup_traverse_info`::\n+\n+\tInitialize a `traverse_info` given the pathname of the tree to start\n+\ttraversing from. The `base` argument is assumed to be the `path`\n+\tmember of the `name_entry` being recursed into unless the tree is a\n+\ttop-level tree in which case the empty string (\"\") is used.\n+\n+Walking\n+-------\n+\n+`tree_entry`::\n+\n+\tVisit the next entry in a tree. Returns 1 when there are more entries\n+\tleft to visit and 0 when all entries have been visited. This is\n+\tcommonly used in the test of a while loop.\n+\n+`tree_entry_len`::\n+\n+\tCalculate the length of a tree entry's pathname. This utilizes the\n+\tmemory structure of a tree entry to avoid the overhead of using a\n+\tgeneric strlen().\n+\n+`update_tree_entry`::\n+\n+\tWalk to the next entry in a tree. This is commonly used in conjunction\n+\twith `tree_entry_extract` to inspect the current entry.\n+\n+`tree_entry_extract`::\n+\n+\tDecode the entry currently being visited (the one pointed to by\n+\t`tree_desc's` `entry` member) and return the sha1 of the entry. The\n+\t`pathp` and `modep` arguments are set to the entry's pathname and mode\n+\trespectively.\n+\n+`get_tree_entry`::\n+\n+\tFind an entry in a tree given a pathname and the sha1 of a tree to\n+\tsearch. Returns 0 if the entry is found and -1 otherwise. The third\n+\tand fourth parameters are set to the entry's sha1 and mode\n+\trespectively.\n+\n+Traversing\n+----------\n+\n+`traverse_trees`::\n+\n+\tTraverse `n` number of trees in parallel. The `fn` callback member of\n+\t`traverse_info` is called once for each tree entry.\n+\n+`traverse_callback_t`::\n+\tThe arguments passed to the traverse callback are as follows:\n++\n+* `n` counts the number of tree's being traversed.\n+\n+* `mask` has its nth bit set if the nth tree's entry is valid. (or different?)\n+\n+* `dirmask` has its nth bit set if the nth tree's entry is a directory.\n+\n+* `entry` is an array of size `n` where the nth entry is from the nth tree.\n+\n+* `info` maintains the state of the traversal.\n+\n++\n+Returning a negative value will terminate the traversal. Otherwise the\n+return value is treated as an update mask. If the nth bit is set the nth tree\n+will be updated and if the bit is not set the nth tree entry will be the\n+same in the next callback invocation.\n+\n+`make_traverse_path`::\n+\n+\tGenerate the full pathname of a tree entry based from the root of the\n+\ttraversal. For example, if the traversal has recursed into another\n+\ttree named \"bar\" the pathname of an entry \"baz\" in the \"bar\"\n+\ttree would be \"bar/baz\".\n+\n+`traverse_path_len`::\n+\n+\tCalculate the length of a pathname returned by `make_traverse_path`.\n+\tThis utilizes the memory structure of a tree entry to avoid the\n+\toverhead of using a generic strlen().\n \n (JC, Linus)\n-- \n1.6.4.rc2.22.g65174\n"},{"id":"119031","messageId":"7vtz0vyjz2.fsf@alter.siamese.dyndns.org","threadId":"20270","inReplyTo":"1248844995-13769-1-git-send-email-bebarino@gmail.com","subject":"Re: [RFC/PATCH] technical-docs: document tree-walking API","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-07-29T08:25:05Z","receivedAt":"2009-07-29T08:25:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Stephen Boyd <bebarino@gmail.com> writes:\n\n> Some things to get you started:\n>\n>       - the traversal callback mask parameter\n> \t- a better general usage description at the top\n> \t- add an authors section?\n\nThanks.\n\n> diff --git a/Documentation/technical/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt\n> index e3ddf91..baa382d 100644\n\n> +* `mask` has its nth bit set if the nth tree's entry is valid. (or different?)\n\nnth bit is set when something exists in that tree at the path (entry[nth]\ncould be either a file (regular or symlink) or a directory).\n\n> +* `dirmask` has its nth bit set if the nth tree's entry is a directory.\n\nCorrect.\n\n> +* `entry` is an array of size `n` where the nth entry is from the nth tree.\n> +\n> +* `info` maintains the state of the traversal.\n> +\n> ++\n> +Returning a negative value will terminate the traversal. Otherwise the\n> +return value is treated as an update mask. If the nth bit is set the nth tree\n> +will be updated and if the bit is not set the nth tree entry will be the\n> +same in the next callback invocation.\n\nCorrect.\n"}]}