Documentation/technical/api-revision-walking.txt

   1 revision walking API
   2 ====================
   3
   4 The revision walking API offers functions to build a list of revisions
   5 and then iterate over that list.
   6
   7 Calling sequence
   8 ----------------
   9
  10 The walking API has a given calling sequence: first you need to
  11 initialize a rev_info structure, then add revisions to control what kind
  12 of revision list do you want to get, finally you can iterate over the
  13 revision list.
  14
  15 Functions
  16 ---------
  17
  18 `init_revisions`::
  19
  20         Initialize a rev_info structure with default values. The second
  21         parameter may be NULL or can be prefix path, and then the `.prefix`
  22         variable will be set to it. This is typically the first function you
  23         want to call when you want to deal with a revision list. After calling
  24         this function, you are free to customize options, like set
  25         `.ignore_merges` to 0 if you don't want to ignore merges, and so on. See
  26         `revision.h` for a complete list of available options.
  27
  28 `add_pending_object`::
  29
  30         This function can be used if you want to add commit objects as revision
  31         information. You can use the `UNINTERESTING` object flag to indicate if
  32         you want to include or exclude the given commit (and commits reachable
  33         from the given commit) from the revision list.
  34 +
  35 NOTE: If you have the commits as a string list then you probably want to
  36 use setup_revisions(), instead of parsing each string and using this
  37 function.
  38
  39 `setup_revisions`::
  40
  41         Parse revision information, filling in the `rev_info` structure, and
  42         removing the used arguments from the argument list. Returns the number
  43         of arguments left that weren't recognized, which are also moved to the
  44         head of the argument list. The last parameter is used in case no
  45         parameter given by the first two arguments.
  46
  47 `prepare_revision_walk`::
  48
  49         Prepares the rev_info structure for a walk. You should check if it
  50         returns any error (non-zero return code) and if it does not, you can
  51         start using get_revision() to do the iteration.
  52
  53 `get_revision`::
  54
  55         Takes a pointer to a `rev_info` structure and iterates over it,
  56         returning a `struct commit *` each time you call it. The end of the
  57         revision list is indicated by returning a NULL pointer.
  58
  59 `reset_revision_walk`::
  60
  61         Reset the flags used by the revision walking api. You can use
  62         this to do multiple sequential revision walks.
  63
  64 Data structures
  65 ---------------
  66
  67 Talk about <revision.h>, things like:
  68
  69 * two diff_options, one for path limiting, another for output;
  70 * remaining functions;
  71
  72 (Linus, JC, Dscho)