Add documentation for the index reading api. This also includes documentation for the new api functions introduced in the next patch.
Helped-by: Nguyễn Thái Ngọc Duy <pclo...@gmail.com> Signed-off-by: Thomas Gummerer <t.gumme...@gmail.com> --- Documentation/technical/api-in-core-index.txt | 56 +++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 4 deletions(-) diff --git a/Documentation/technical/api-in-core-index.txt b/Documentation/technical/api-in-core-index.txt index adbdbf5..2cf7a71 100644 --- a/Documentation/technical/api-in-core-index.txt +++ b/Documentation/technical/api-in-core-index.txt @@ -1,14 +1,62 @@ in-core index API ================= +Reading API +----------- + +`cache`:: + + An array of cache entries. This is used to access the cache + entries directly. Use `index_name_pos` to search for the + index of a specific cache entry. + +`read_index_filtered`:: + + Read a part of the index, filtered by the pathspec given in + the opts. The function may load more than necessary, so the + caller is still responsible for applying filters appropriately. The + filtering is only done for performance reasons, as it's + possible to only read part of the index when the on-disk + format is index-v5. ++ +To iterate only over the entries that match the pathspec, use +the for_each_index_entry function. + +`read_index`:: + + Read the whole index file from disk. + +`index_name_pos`:: + + Find a cache_entry with name in the index. Returns pos if an + entry is matched exactly and -1-pos if an entry is matched + partially. e.g. ++ +.... +index: + file1 + file2 + path/file1 + zzz +.... ++ +`index_name_pos("path/file1", 10)` returns 2, while +`index_name_pos("path", 4)` returns -3 + +`for_each_index_entry`:: + + Iterates over all cache_entries in the index filtered by + filter_opts in the index_state. For each cache entry fn is + executed with cb_data as callback data. From within the loop + do `return 0` to continue, or `return 1` to break the loop. + +TODO +---- Talk about <read-cache.c> and <cache-tree.c>, things like: -* cache -> the_index macros -* read_index() * write_index() * ie_match_stat() and ie_modified(); how they are different and when to use which. -* index_name_pos() * remove_index_entry_at() * remove_file_from_index() * add_file_to_index() @@ -18,4 +66,4 @@ Talk about <read-cache.c> and <cache-tree.c>, things like: * cache_tree_invalidate_path() * cache_tree_update() -(JC, Linus) +(JC, Linus, Thomas Gummerer) -- 22.214.171.124 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html