Miklos Vajna <vmiklos@xxxxxxxxxxxxxx> writes: > Unfortunately the list is not complete, but includes the essential ones. > ... > Here is a start. To be honest I never used the functions I did not > document, so I don't have too much idea what they do (not counting > reading the source ;-) ), so I thought it's better if I leave them > excluded from the list. It's a good start. Thanks. > revision walking API > ==================== > > +The revision walking API offers functions to build a list of revisions > +and then iterate over that list. > +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. I think this paragraph is easier to read if it is in its own subsection "Calling Sequence" (see api-diff.txt for an example). > +Functions > +--------- > + > +`init_revisions`:: > + > + Initialize a rev_info structure with default values. The second > + 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. Traversal options are numerous and complex, so I agree that it makes sense to refer the reader elsewhere. We can start with "revision.h", and extend this documentation by adding a separate section on it. > +`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 (positive return code) and if it does not, you can s/positive/non-zero/; -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
