Teach revision walking machinery to walk multiple times sequencially
[git/git.git] / Documentation / technical / api-revision-walking.txt
CommitLineData
530e741c
JH
1revision walking API
2====================
3
c16570c4
MV
4The revision walking API offers functions to build a list of revisions
5and then iterate over that list.
6
7Calling sequence
8----------------
9
10The walking API has a given calling sequence: first you need to
11initialize a rev_info structure, then add revisions to control what kind
12of revision list do you want to get, finally you can iterate over the
13revision list.
14
15Functions
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+
35NOTE: If you have the commits as a string list then you probably want to
36use setup_revisions(), instead of parsing each string and using this
37function.
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
62 this to do multiple sequencial revision walks.
63
c16570c4
MV
64Data structures
65---------------
66
530e741c
JH
67Talk about <revision.h>, things like:
68
69* two diff_options, one for path limiting, another for output;
c16570c4 70* remaining functions;
530e741c
JH
71
72(Linus, JC, Dscho)