| 1 | Path-Walk API |
| 2 | ============= |
| 3 | |
| 4 | The path-walk API is used to walk reachable objects, but to visit objects |
| 5 | in batches based on a common path they appear in, or by type. |
| 6 | |
| 7 | For example, all reachable commits are visited in a group. All tags are |
| 8 | visited in a group. Then, all root trees are visited. At some point, all |
| 9 | blobs reachable via a path `my/dir/to/A` are visited. When there are |
| 10 | multiple paths possible to reach the same object, then only one of those |
| 11 | paths is used to visit the object. |
| 12 | |
| 13 | Basics |
| 14 | ------ |
| 15 | |
| 16 | To use the path-walk API, include `path-walk.h` and call |
| 17 | `walk_objects_by_path()` with a customized `path_walk_info` struct. The |
| 18 | struct is used to set all of the options for how the walk should proceed. |
| 19 | Let'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 | + |
| 37 | It 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 |
| 39 | the objects will be walked in a separate way based on those starting |
| 40 | commits. |
| 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 | + |
| 51 | Note that objects directly requested as pending objects (such as targets |
| 52 | of lightweight tags or other ref tips) are always emitted to `path_fn`, |
| 53 | even when the corresponding type flag is disabled. Only objects |
| 54 | discovered during the tree walk are subject to these type filters. This |
| 55 | ensures that objects specifically requested through the revision input |
| 56 | are never silently dropped. |
| 57 | + |
| 58 | While it is possible to walk only commits in this way, consumers would be |
| 59 | better off using the revision walk API instead. |
| 60 | |
| 61 | `prune_all_uninteresting`:: |
| 62 | By default, all reachable paths are emitted by the path-walk API. |
| 63 | This option allows consumers to declare that they are not |
| 64 | interested in paths where all included objects are marked with the |
| 65 | `UNINTERESTING` flag. This requires using the `boundary` option in |
| 66 | the revision walk so that the walk emits commits marked with the |
| 67 | `UNINTERESTING` flag. |
| 68 | |
| 69 | `edge_aggressive`:: |
| 70 | For performance reasons, usually only the boundary commits are |
| 71 | explored to find UNINTERESTING objects. However, in the case of |
| 72 | shallow clones it can be helpful to mark all trees and blobs |
| 73 | reachable from UNINTERESTING tip commits as UNINTERESTING. This |
| 74 | matches the behavior of `--objects-edge-aggressive` in the |
| 75 | revision API. |
| 76 | |
| 77 | `pl`:: |
| 78 | This pattern list pointer allows focusing the path-walk search to |
| 79 | a set of patterns, only emitting paths that match the given |
| 80 | patterns. See linkgit:gitignore[5] or |
| 81 | linkgit:git-sparse-checkout[1] for details about pattern lists. |
| 82 | When the pattern list uses cone-mode patterns, then the path-walk |
| 83 | API can prune the set of paths it walks to improve performance. |
| 84 | |
| 85 | Examples |
| 86 | -------- |
| 87 | |
| 88 | See example usages in: |
| 89 | `t/helper/test-path-walk.c`, |
| 90 | `builtin/pack-objects.c`, |
| 91 | `builtin/backfill.c` |