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 <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
301d595e7271662d2e8456d1ef68ede09b5b99a6
3 files changed
+60
-73
Documentation/MyFirstObjectWalk.txt
+1
-1
@@ -17,7 +17,7 @@ revision walk is used for operations like `git log`.
17
18
- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of
19
the revision walker in its various incarnations.
20
-- `Documentation/technical/api-revision-walking.txt`
20
+- `revision.h`
21
- https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists]
22
gives a good overview of the types of objects in Git and what your object
23
walk is really describing.
Documentation/technical/api-revision-walking.txt
deleted
-72
@@ -1,72 +0,0 @@
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
-`repo_init_revisions`::
19
-
20
- Initialize a rev_info structure with default values. The third
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
-`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
-
64
-Data structures
65
----------------
66
-
67
-Talk 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)
revision.h
+59
@@ -9,6 +9,19 @@
9
#include "diff.h"
10
#include "commit-slab-decl.h"
11
12
+/**
13
+ * The revision walking API offers functions to build a list of revisions
14
+ * and then iterate over that list.
15
+ *
16
+ * Calling sequence
17
+ * ----------------
18
+ *
19
+ * The walking API has a given calling sequence: first you need to initialize
20
+ * a rev_info structure, then add revisions to control what kind of revision
21
+ * list do you want to get, finally you can iterate over the revision list.
22
+ *
23
+ */
24
+
25
/* Remember to update object flag allocation in object.h */
26
#define SEEN (1u<<0)
27
#define UNINTERESTING (1u<<1)
@@ -306,11 +319,29 @@ struct setup_revision_opt {
319
#ifndef NO_THE_REPOSITORY_COMPATIBILITY_MACROS
320
#define init_revisions(revs, prefix) repo_init_revisions(the_repository, revs, prefix)
321
#endif
322
+
323
+/**
324
+ * Initialize a rev_info structure with default values. The third parameter may
325
+ * be NULL or can be prefix path, and then the `.prefix` variable will be set
326
+ * to it. This is typically the first function you want to call when you want
327
+ * to deal with a revision list. After calling this function, you are free to
328
+ * customize options, like set `.ignore_merges` to 0 if you don't want to
329
+ * ignore merges, and so on.
330
+ */
331
void repo_init_revisions(struct repository *r,
332
struct rev_info *revs,
333
const char *prefix);
334
+
335
+/**
336
+ * Parse revision information, filling in the `rev_info` structure, and
337
+ * removing the used arguments from the argument list. Returns the number
338
+ * of arguments left that weren't recognized, which are also moved to the
339
+ * head of the argument list. The last parameter is used in case no
340
+ * parameter given by the first two arguments.
341
+ */
342
int setup_revisions(int argc, const char **argv, struct rev_info *revs,
343
struct setup_revision_opt *);
344
+
345
void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx,
346
const struct option *options,
347
const char * const usagestr[]);
@@ -319,9 +350,26 @@ void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx,
350
int handle_revision_arg(const char *arg, struct rev_info *revs,
351
int flags, unsigned revarg_opt);
352
353
+/**
354
+ * Reset the flags used by the revision walking api. You can use this to do
355
+ * multiple sequential revision walks.
356
+ */
357
void reset_revision_walk(void);
358
+
359
+/**
360
+ * Prepares the rev_info structure for a walk. You should check if it returns
361
+ * any error (non-zero return code) and if it does not, you can start using
362
+ * get_revision() to do the iteration.
363
+ */
364
int prepare_revision_walk(struct rev_info *revs);
365
+
366
+/**
367
+ * Takes a pointer to a `rev_info` structure and iterates over it, returning a
368
+ * `struct commit *` each time you call it. The end of the revision list is
369
+ * indicated by returning a NULL pointer.
370
+ */
371
struct commit *get_revision(struct rev_info *revs);
372
+
373
char *get_revision_mark(const struct rev_info *revs,
374
const struct commit *commit);
375
void put_revision_mark(const struct rev_info *revs,
@@ -333,8 +381,19 @@ void mark_trees_uninteresting_sparse(struct repository *r, struct oidset *trees)
381
382
void show_object_with_name(FILE *, struct object *, const char *);
383
384
+/**
385
+ * This function can be used if you want to add commit objects as revision
386
+ * information. You can use the `UNINTERESTING` object flag to indicate if
387
+ * you want to include or exclude the given commit (and commits reachable
388
+ * from the given commit) from the revision list.
389
+ *
390
+ * NOTE: If you have the commits as a string list then you probably want to
391
+ * use setup_revisions(), instead of parsing each string and using this
392
+ * function.
393
+ */
394
void add_pending_object(struct rev_info *revs,
395
struct object *obj, const char *name);
396
+
397
void add_pending_oid(struct rev_info *revs,
398
const char *name, const struct object_id *oid,
399
unsigned int flags);