MyFirstObjectWalk: update recommended usage
The previous change consolidated traverse_commit_list() and traverse_commit_list_filtered(). This allows us to simplify the recommended usage in MyFirstObjectWalk.txt to use this new set of values. While here, add some clarification on the difference between the two methods. Signed-off-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Derrick Stolee committed
Mar 9, 2022 at 16:01 UTC
f0d2f84919885d4dfb940e79a8e340bd2ad1887d
1 file changed
+16
-28
Documentation/MyFirstObjectWalk.txt
+16
-28
@@ -522,24 +522,25 @@ function shows that the all-object walk is being performed by
522
`traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two
523
functions reside in `list-objects.c`; examining the source shows that, despite
524
the name, these functions traverse all kinds of objects. Let's have a look at
525
-the arguments to `traverse_commit_list_filtered()`, which are a superset of the
526
-arguments to the unfiltered version.
525
+the arguments to `traverse_commit_list()`.
526
528
-- `struct list_objects_filter_options *filter_options`: This is a struct which
529
- stores a filter-spec as outlined in `Documentation/rev-list-options.txt`.
530
-- `struct rev_info *revs`: This is the `rev_info` used for the walk.
527
+- `struct rev_info *revs`: This is the `rev_info` used for the walk. If
528
+ its `filter` member is not `NULL`, then `filter` contains information for
529
+ how to filter the object list.
530
- `show_commit_fn show_commit`: A callback which will be used to handle each
531
individual commit object.
532
- `show_object_fn show_object`: A callback which will be used to handle each
533
non-commit object (so each blob, tree, or tag).
534
- `void *show_data`: A context buffer which is passed in turn to `show_commit`
535
and `show_object`.
536
+
537
+In addition, `traverse_commit_list_filtered()` has an additional paramter:
538
+
539
- `struct oidset *omitted`: A linked-list of object IDs which the provided
540
filter caused to be omitted.
541
540
-It looks like this `traverse_commit_list_filtered()` uses callbacks we provide
541
-instead of needing us to call it repeatedly ourselves. Cool! Let's add the
542
-callbacks first.
542
+It looks like these methods use callbacks we provide instead of needing us
543
+to call it repeatedly ourselves. Cool! Let's add the callbacks first.
544
545
For the sake of this tutorial, we'll simply keep track of how many of each kind
546
of object we find. At file scope in `builtin/walken.c` add the following
@@ -712,20 +713,9 @@ help understand. In our case, that means we omit trees and blobs not directly
713
referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only
714
`HEAD` in the `pending` list.)
715
715
-First, we'll need to `#include "list-objects-filter-options.h"` and set up the
716
-`struct list_objects_filter_options` at the top of the function.
717
-
718
-----
719
-static void walken_object_walk(struct rev_info *rev)
720
-{
721
- struct list_objects_filter_options filter_options = { 0 };
722
-
723
- ...
724
-----
725
-
716
For now, we are not going to track the omitted objects, so we'll replace those
717
parameters with `NULL`. For the sake of simplicity, we'll add a simple
728
-build-time branch to use our filter or not. Replace the line calling
718
+build-time branch to use our filter or not. Preface the line calling
719
`traverse_commit_list()` with the following, which will remind us which kind of
720
walk we've just performed:
721
@@ -733,19 +723,17 @@ walk we've just performed:
723
if (0) {
724
/* Unfiltered: */
725
trace_printf(_("Unfiltered object walk.\n"));
736
- traverse_commit_list(rev, walken_show_commit,
737
- walken_show_object, NULL);
726
} else {
727
trace_printf(
728
_("Filtered object walk with filterspec 'tree:1'.\n"));
741
- parse_list_objects_filter(&filter_options, "tree:1");
742
-
743
- traverse_commit_list_filtered(&filter_options, rev,
744
- walken_show_commit, walken_show_object, NULL, NULL);
729
+ CALLOC_ARRAY(rev->filter, 1);
730
+ parse_list_objects_filter(rev->filter, "tree:1");
731
}
732
+ traverse_commit_list(rev, walken_show_commit,
733
+ walken_show_object, NULL);
734
----
735
748
-`struct list_objects_filter_options` is usually built directly from a command
736
+The `rev->filter` member is usually built directly from a command
737
line argument, so the module provides an easy way to build one from a string.
738
Even though we aren't taking user input right now, we can still build one with
739
a hardcoded string using `parse_list_objects_filter()`.
@@ -784,7 +772,7 @@ object:
772
----
773
...
774
787
- traverse_commit_list_filtered(&filter_options, rev,
775
+ traverse_commit_list_filtered(rev,
776
walken_show_commit, walken_show_object, NULL, &omitted);
777
778
...