From 301d595e7271662d2e8456d1ef68ede09b5b99a6 Mon Sep 17 00:00:00 2001 From: Heba Waly Date: Sun, 17 Nov 2019 21:04:48 +0000 Subject: 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 --- revision.h | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'revision.h') diff --git a/revision.h b/revision.h index 4134dc6029..983ffc0f12 100644 --- a/revision.h +++ b/revision.h @@ -9,6 +9,19 @@ #include "diff.h" #include "commit-slab-decl.h" +/** + * 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. + * + */ + /* Remember to update object flag allocation in object.h */ #define SEEN (1u<<0) #define UNINTERESTING (1u<<1) @@ -306,11 +319,29 @@ struct setup_revision_opt { #ifndef NO_THE_REPOSITORY_COMPATIBILITY_MACROS #define init_revisions(revs, prefix) repo_init_revisions(the_repository, revs, prefix) #endif + +/** + * 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. + */ void repo_init_revisions(struct repository *r, struct rev_info *revs, const char *prefix); + +/** + * 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. + */ int setup_revisions(int argc, const char **argv, struct rev_info *revs, struct setup_revision_opt *); + void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, const struct option *options, const char * const usagestr[]); @@ -319,9 +350,26 @@ void parse_revision_opt(struct rev_info *revs, struct parse_opt_ctx_t *ctx, int handle_revision_arg(const char *arg, struct rev_info *revs, int flags, unsigned revarg_opt); +/** + * Reset the flags used by the revision walking api. You can use this to do + * multiple sequential revision walks. + */ void reset_revision_walk(void); + +/** + * 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. + */ int prepare_revision_walk(struct rev_info *revs); + +/** + * 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. + */ struct commit *get_revision(struct rev_info *revs); + char *get_revision_mark(const struct rev_info *revs, const struct commit *commit); void put_revision_mark(const struct rev_info *revs, @@ -333,8 +381,19 @@ void mark_trees_uninteresting_sparse(struct repository *r, struct oidset *trees) void show_object_with_name(FILE *, struct object *, const char *); +/** + * 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. + */ void add_pending_object(struct rev_info *revs, struct object *obj, const char *name); + void add_pending_oid(struct rev_info *revs, const char *name, const struct object_id *oid, unsigned int flags); -- cgit v1.2.3 From 4982516451ed4979bc7fc1a7f002fc310b060118 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 19 Nov 2019 16:51:13 -0800 Subject: revision: make get_revision_mark() return const pointer get_revision_mark() used to return a `char *`, even though all of the strings it was returning were string literals. Make get_revision_mark() return a `const char *` so that callers won't be tempted to modify the returned string. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- revision.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'revision.h') diff --git a/revision.h b/revision.h index 4134dc6029..addd69410b 100644 --- a/revision.h +++ b/revision.h @@ -322,8 +322,8 @@ int handle_revision_arg(const char *arg, struct rev_info *revs, void reset_revision_walk(void); int prepare_revision_walk(struct rev_info *revs); struct commit *get_revision(struct rev_info *revs); -char *get_revision_mark(const struct rev_info *revs, - const struct commit *commit); +const char *get_revision_mark(const struct rev_info *revs, + const struct commit *commit); void put_revision_mark(const struct rev_info *revs, const struct commit *commit); -- cgit v1.2.3 From 1d7297513df66873e68af4b254804151b8ba5359 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 11 Dec 2019 16:49:50 -0800 Subject: notes: break set_display_notes() into smaller functions In 8164c961e1 (format-patch: use --notes behavior for format.notes, 2019-12-09), we introduced set_display_notes() which was a monolithic function with three mutually exclusive branches. Break the function up into three small and simple functions that each are only responsible for one task. This family of functions accepts an `int *show_notes` instead of returning a value suitable for assignment to `show_notes`. This is for two reasons. First of all, this guarantees that the external `show_notes` variable changes in lockstep with the `struct display_notes_opt`. Second, this prompts future developers to be careful about doing something meaningful with this value. In fact, a NULL check is intentionally omitted because causing a segfault here would tell the future developer that they are meant to use the value for something meaningful. One alternative was making the family of functions accept a `struct rev_info *` instead of the `struct display_notes_opt *`, since the former contains the `show_notes` field as well. This does not work because we have to call git_config() before repo_init_revisions(). However, if we had a `struct rev_info`, we'd need to initialize it before it gets assigned values from git_config(). As a result, we break the circular dependency by having standalone `int show_notes` and `struct display_notes_opt notes_opt` variables which temporarily hold values from git_config() until the values are copied over to `rev`. To implement this change, we need to get a pointer to `rev_info::show_notes`. Unfortunately, this is not possible with bitfields and only direct-assignment is possible. Change `rev_info::show_notes` to a non-bitfield int so that we can get its address. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- revision.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'revision.h') diff --git a/revision.h b/revision.h index 4134dc6029..72520780f4 100644 --- a/revision.h +++ b/revision.h @@ -177,10 +177,10 @@ struct rev_info { always_show_header:1; /* Format info */ + int show_notes; unsigned int shown_one:1, shown_dashes:1, show_merge:1, - show_notes:1, show_notes_given:1, show_signature:1, pretty_given:1, -- cgit v1.2.3