1revision walking API 2==================== 3 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 59`reset_revision_walk`:: 60 61 Reset the flags used by the revision walking api. You can use 62 this to do multiple sequential revision walks. 63 64Data structures 65--------------- 66 67Talk about <revision.h>, things like: 68 69* two diff_options, one for path limiting, another for output; 70* remaining functions; 71 72(Linus, JC, Dscho)