72 lines
2.4 KiB
Text
72 lines
2.4 KiB
Text
revision walking API
|
|
====================
|
|
|
|
The revision walking API offers functions to build a list of revisions
|
|
and then iterate over that list.
|
|
|
|
Calling sequence
|
|
----------------
|
|
|
|
The walking API has a given calling sequence: first you need to
|
|
initialize a rev_info structure, then add revisions to control what kind
|
|
of revision list do you want to get, finally you can iterate over the
|
|
revision list.
|
|
|
|
Functions
|
|
---------
|
|
|
|
`repo_init_revisions`::
|
|
|
|
Initialize a rev_info structure with default values. The third
|
|
parameter may be NULL or can be prefix path, and then the `.prefix`
|
|
variable will be set to it. This is typically the first function you
|
|
want to call when you want to deal with a revision list. After calling
|
|
this function, you are free to customize options, like set
|
|
`.ignore_merges` to 0 if you don't want to ignore merges, and so on. See
|
|
`revision.h` for a complete list of available options.
|
|
|
|
`add_pending_object`::
|
|
|
|
This function can be used if you want to add commit objects as revision
|
|
information. You can use the `UNINTERESTING` object flag to indicate if
|
|
you want to include or exclude the given commit (and commits reachable
|
|
from the given commit) from the revision list.
|
|
+
|
|
NOTE: If you have the commits as a string list then you probably want to
|
|
use setup_revisions(), instead of parsing each string and using this
|
|
function.
|
|
|
|
`setup_revisions`::
|
|
|
|
Parse revision information, filling in the `rev_info` structure, and
|
|
removing the used arguments from the argument list. Returns the number
|
|
of arguments left that weren't recognized, which are also moved to the
|
|
head of the argument list. The last parameter is used in case no
|
|
parameter given by the first two arguments.
|
|
|
|
`prepare_revision_walk`::
|
|
|
|
Prepares the rev_info structure for a walk. You should check if it
|
|
returns any error (non-zero return code) and if it does not, you can
|
|
start using get_revision() to do the iteration.
|
|
|
|
`get_revision`::
|
|
|
|
Takes a pointer to a `rev_info` structure and iterates over it,
|
|
returning a `struct commit *` each time you call it. The end of the
|
|
revision list is indicated by returning a NULL pointer.
|
|
|
|
`reset_revision_walk`::
|
|
|
|
Reset the flags used by the revision walking api. You can use
|
|
this to do multiple sequential revision walks.
|
|
|
|
Data structures
|
|
---------------
|
|
|
|
Talk about <revision.h>, things like:
|
|
|
|
* two diff_options, one for path limiting, another for output;
|
|
* remaining functions;
|
|
|
|
(Linus, JC, Dscho)
|