freshlybakedca.ke
Git fork
1Path-Walk API
2=============
3
4The path-walk API is used to walk reachable objects, but to visit objects
5in batches based on a common path they appear in, or by type.
6
7For example, all reachable commits are visited in a group. All tags are
8visited in a group. Then, all root trees are visited. At some point, all
9blobs reachable via a path `my/dir/to/A` are visited. When there are
10multiple paths possible to reach the same object, then only one of those
11paths is used to visit the object.
12
13Basics
14------
15
16To use the path-walk API, include `path-walk.h` and call
17`walk_objects_by_path()` with a customized `path_walk_info` struct. The
18struct is used to set all of the options for how the walk should proceed.
19Let's dig into the different options and their use.
20
21`path_fn` and `path_fn_data`::
22 The most important option is the `path_fn` option, which is a
23 function pointer to the callback that can execute logic on the
24 object IDs for objects grouped by type and path. This function
25 also receives a `data` value that corresponds to the
26 `path_fn_data` member, for providing custom data structures to
27 this callback function.
28
29`revs`::
30 To configure the exact details of the reachable set of objects,
31 use the `revs` member and initialize it using the revision
32 machinery in `revision.h`. Initialize `revs` using calls such as
33 `setup_revisions()` or `parse_revision_opt()`. Do not call
34 `prepare_revision_walk()`, as that will be called within
35 `walk_objects_by_path()`.
36+
37It is also important that you do not specify the `--objects` flag for the
38`revs` struct. The revision walk should only be used to walk commits, and
39the objects will be walked in a separate way based on those starting
40commits.
41
42`commits`::
43`blobs`::
44`trees`::
45`tags`::
46 By default, these members are enabled and signal that the path-walk
47 API should call the `path_fn` on objects of these types. Specialized
48 applications could disable some options to make it simpler to walk
49 the objects or to have fewer calls to `path_fn`.
50+
51While it is possible to walk only commits in this way, consumers would be
52better off using the revision walk API instead.
53
54`prune_all_uninteresting`::
55 By default, all reachable paths are emitted by the path-walk API.
56 This option allows consumers to declare that they are not
57 interested in paths where all included objects are marked with the
58 `UNINTERESTING` flag. This requires using the `boundary` option in
59 the revision walk so that the walk emits commits marked with the
60 `UNINTERESTING` flag.
61
62`edge_aggressive`::
63 For performance reasons, usually only the boundary commits are
64 explored to find UNINTERESTING objects. However, in the case of
65 shallow clones it can be helpful to mark all trees and blobs
66 reachable from UNINTERESTING tip commits as UNINTERESTING. This
67 matches the behavior of `--objects-edge-aggressive` in the
68 revision API.
69
70`pl`::
71 This pattern list pointer allows focusing the path-walk search to
72 a set of patterns, only emitting paths that match the given
73 patterns. See linkgit:gitignore[5] or
74 linkgit:git-sparse-checkout[1] for details about pattern lists.
75 When the pattern list uses cone-mode patterns, then the path-walk
76 API can prune the set of paths it walks to improve performance.
77
78Examples
79--------
80
81See example usages in:
82 `t/helper/test-path-walk.c`,
83 `builtin/pack-objects.c`,
84 `builtin/backfill.c`