[thirdparty/git.git] / Documentation / technical / api-revision-walking.txt

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)
Commit	Line	Data
530e741c JH	1	revision walking API
	2	====================
	3
c16570c4 MV	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
2abf3503	18	`repo_init_revisions`::
c16570c4	19
2abf3503	20	Initialize a rev_info structure with default values. The third
c16570c4 MV	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
bcc0a3ea HV	59	`reset_revision_walk`::
	60
	61	Reset the flags used by the revision walking api. You can use
98e023de	62	this to do multiple sequential revision walks.
bcc0a3ea	63
c16570c4 MV	64	Data structures
	65	---------------
	66
530e741c JH	67	Talk about <revision.h>, things like:
	68
	69	* two diff_options, one for path limiting, another for output;
c16570c4	70	* remaining functions;
530e741c JH	71
530e741c JH	72	(Linus, JC, Dscho)