Documentation/technical/api-path-walk.txt

   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`, `blobs`, `trees`, `tags`::
  43         By default, these members are enabled and signal that the path-walk
  44         API should call the `path_fn` on objects of these types. Specialized
  45         applications could disable some options to make it simpler to walk
  46         the objects or to have fewer calls to `path_fn`.
  47 +
  48 While it is possible to walk only commits in this way, consumers would be
  49 better off using the revision walk API instead.
  50
  51 `prune_all_uninteresting`::
  52         By default, all reachable paths are emitted by the path-walk API.
  53         This option allows consumers to declare that they are not
  54         interested in paths where all included objects are marked with the
  55         `UNINTERESTING` flag. This requires using the `boundary` option in
  56         the revision walk so that the walk emits commits marked with the
  57         `UNINTERESTING` flag.
  58
  59 Examples
  60 --------
  61
  62 See example usages in:
  63         `t/helper/test-path-walk.c`