]>
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 | ||
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 | ||
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 |
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 | |
72 | (Linus, JC, Dscho) |