Revision walking documentation: document most important functions
Unfortunately the list is not complete, but includes the essential ones. Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Miklos Vajna committed
May 31, 2008 at 02:18 UTC
c16570c42a748a29031281badd4762dd4e71d3d0
1 file changed
+59
-1
Documentation/technical/api-revision-walking.txt
+59
-1
@@ -1,9 +1,67 @@
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
+Data structures
60
+---------------
61
+
62
Talk about <revision.h>, things like:
63
64
* two diff_options, one for path limiting, another for output;
7
-* calling sequence: init_revisions(), setup_revsions(), get_revision();
65
+* remaining functions;
66
67
(Linus, JC, Dscho)