for_each_*_object: give more comprehensive docstrings
We already mention the local/alternate behavior of these functions, but we can help clarify a few other behaviors: - there's no need to mention LOCAL_ONLY specifically, since we already reference the flags by type (and as we add more flags, we don't want to have to mention each) - clarify that reachability doesn't matter here; this is all accessible objects - what ordering/uniqueness guarantees we give - how pack-specific flags are handled for the loose case Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Aug 10, 2018 at 19:11 UTC
8b361551900be9bedd946386362f2d0e2a506845
2 files changed
+13
-7
cache.h
+5
-3
@@ -1636,9 +1636,11 @@ enum for_each_object_flags {
1636
};
1637
1638
/*
1639
- * Iterate over loose objects in both the local
1640
- * repository and any alternates repositories (unless the
1641
- * LOCAL_ONLY flag is set).
1639
+ * Iterate over all accessible loose objects without respect to
1640
+ * reachability. By default, this includes both local and alternate objects.
1641
+ * The order in which objects are visited is unspecified.
1642
+ *
1643
+ * Any flags specific to packs are ignored.
1644
*/
1645
int for_each_loose_object(each_loose_object_fn, void *,
1646
enum for_each_object_flags flags);
packfile.h
+8
-4
@@ -149,10 +149,14 @@ extern int has_object_pack(const struct object_id *oid);
149
extern int has_pack_index(const unsigned char *sha1);
150
151
/*
152
- * Iterate over packed objects in both the local
153
- * repository and any alternates repositories (unless the
154
- * FOR_EACH_OBJECT_LOCAL_ONLY flag is set). See cache.h for the complete list
155
- * of flags.
152
+ * Iterate over all accessible packed objects without respect to reachability.
153
+ * By default, this includes both local and alternate packs.
154
+ *
155
+ * Note that some objects may appear twice if they are found in multiple packs.
156
+ * Each pack is visited in an unspecified order. Objects within a pack are
157
+ * visited in pack-idx order (i.e., sorted by oid).
158
+ *
159
+ * The list of flags can be found in cache.h.
160
*/
161
typedef int each_packed_object_fn(const struct object_id *oid,
162
struct packed_git *pack,