path: root/Documentation/technical/api-revision-walking.txt
diff options
authorHeba Waly <>2019-11-17 21:04:48 (GMT)
committerJunio C Hamano <>2019-11-18 06:21:28 (GMT)
commit301d595e7271662d2e8456d1ef68ede09b5b99a6 (patch)
treefb623bfb60441d0a525a8aa02675d263bf2589af /Documentation/technical/api-revision-walking.txt
parent3a1b3415d9330cbe3d3cce125b971dff96d0aa4c (diff)
revision: move doc to revision.h
Move the documentation from Documentation/technical/api-revision-walking.txt to revision.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Also documentation/technical/api-revision-walking.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical/api-revision-walking.txt')
1 files changed, 0 insertions, 72 deletions
diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
deleted file mode 100644
index 03f9ea6..0000000
--- a/Documentation/technical/api-revision-walking.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-revision walking API
-The revision walking API offers functions to build a list of revisions
-and then iterate over that list.
-Calling sequence
-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.
- Initialize a rev_info structure with default values. The third
- 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.
- 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
- 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.
- Prepares the rev_info structure for a walk. You should check if it
- returns any error (non-zero return code) and if it does not, you can
- start using get_revision() to do the iteration.
- Takes a pointer to a `rev_info` structure and iterates over it,
- returning a `struct commit *` each time you call it. The end of the
- revision list is indicated by returning a NULL pointer.
- Reset the flags used by the revision walking api. You can use
- this to do multiple sequential revision walks.
-Data structures
-Talk about <revision.h>, things like:
-* two diff_options, one for path limiting, another for output;
-* remaining functions;
-(Linus, JC, Dscho)