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@xxxxxxxx>
---
cache.h | 8 +++++---
packfile.h | 12 ++++++++----
2 files changed, 13 insertions(+), 7 deletions(-)
diff --git a/cache.h b/cache.h
index 9e02fc494e..f438540f9b 100644
--- a/cache.h
+++ b/cache.h
@@ -1636,9 +1636,11 @@ enum for_each_object_flags {
};
/*
- * Iterate over loose objects in both the local
- * repository and any alternates repositories (unless the
- * LOCAL_ONLY flag is set).
+ * Iterate over all accessible loose objects without respect to
+ * reachability. By default, this includes both local and alternate objects.
+ * The order in which objects are visited is unspecified.
+ *
+ * Any flags specific to packs are ignored.
*/
int for_each_loose_object(each_loose_object_fn, void *,
enum for_each_object_flags flags);
diff --git a/packfile.h b/packfile.h
index 9861728514..c86a8c2716 100644
--- a/packfile.h
+++ b/packfile.h
@@ -149,10 +149,14 @@ extern int has_object_pack(const struct object_id *oid);
extern int has_pack_index(const unsigned char *sha1);
/*
- * Iterate over packed objects in both the local
- * repository and any alternates repositories (unless the
- * FOR_EACH_OBJECT_LOCAL_ONLY flag is set). See cache.h for the complete list
- * of flags.
+ * Iterate over all accessible packed objects without respect to reachability.
+ * By default, this includes both local and alternate packs.
+ *
+ * Note that some objects may appear twice if they are found in multiple packs.
+ * Each pack is visited in an unspecified order. Objects within a pack are
+ * visited in pack-idx order (i.e., sorted by oid).
+ *
+ * The list of flags can be found in cache.h.
*/
typedef int each_packed_object_fn(const struct object_id *oid,
struct packed_git *pack,
--
2.18.0.1058.g7433f71063
