refs-internal.h: reorganize DO_FOR_EACH_* flag documentation
The documentation for the DO_FOR_EACH_* flags is sprinkled over the refs-internal.h file. We define the two flags in one spot, and then describe them in more detail far away from there, in the definitions of refs_ref_iterator_begin() and ref_iterator_advance_fn(). Let's try to organize this a bit better: - convert the #defines to an enum. This makes it clear that they are related, and that the enum shows the complete set of flags. - combine all descriptions for each flag in a single spot, next to the flag's definition - use the enum rather than a bare int for functions which take the flags. This helps readers realize which flags can be used. - clarify the mention of flags for ref_iterator_advance_fn(). It does not take flags itself, but is meant to depend on ones set up earlier. Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Sep 24, 2021 at 14:39 UTC
9aab952e855be1a567d4d0585afbdbde624e274f
2 files changed
+33
-23
refs.c
+6
-4
@@ -1413,7 +1413,8 @@ int head_ref(each_ref_fn fn, void *cb_data)
1413
1414
struct ref_iterator *refs_ref_iterator_begin(
1415
struct ref_store *refs,
1416
- const char *prefix, int trim, int flags)
1416
+ const char *prefix, int trim,
1417
+ enum do_for_each_ref_flags flags)
1418
{
1419
struct ref_iterator *iter;
1420
@@ -1479,7 +1480,8 @@ static int do_for_each_ref_helper(struct repository *r,
1480
}
1481
1482
static int do_for_each_ref(struct ref_store *refs, const char *prefix,
1482
- each_ref_fn fn, int trim, int flags, void *cb_data)
1483
+ each_ref_fn fn, int trim,
1484
+ enum do_for_each_ref_flags flags, void *cb_data)
1485
{
1486
struct ref_iterator *iter;
1487
struct do_for_each_ref_help hp = { fn, cb_data };
@@ -1516,7 +1518,7 @@ int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data)
1518
1519
int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data, unsigned int broken)
1520
{
1519
- unsigned int flag = 0;
1521
+ enum do_for_each_ref_flags flag = 0;
1522
1523
if (broken)
1524
flag = DO_FOR_EACH_INCLUDE_BROKEN;
@@ -1528,7 +1530,7 @@ int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix,
1530
each_ref_fn fn, void *cb_data,
1531
unsigned int broken)
1532
{
1531
- unsigned int flag = 0;
1533
+ enum do_for_each_ref_flags flag = 0;
1534
1535
if (broken)
1536
flag = DO_FOR_EACH_INCLUDE_BROKEN;
refs/refs-internal.h
+27
-19
@@ -245,16 +245,30 @@ int refs_rename_ref_available(struct ref_store *refs,
245
/* We allow "recursive" symbolic refs. Only within reason, though */
246
#define SYMREF_MAXDEPTH 5
247
248
-/* Include broken references in a do_for_each_ref*() iteration: */
249
-#define DO_FOR_EACH_INCLUDE_BROKEN 0x01
250
-
248
/*
252
- * Only include per-worktree refs in a do_for_each_ref*() iteration.
253
- * Normally this will be used with a files ref_store, since that's
254
- * where all reference backends will presumably store their
255
- * per-worktree refs.
249
+ * These flags are passed to refs_ref_iterator_begin() (and do_for_each_ref(),
250
+ * which feeds it).
251
*/
257
-#define DO_FOR_EACH_PER_WORKTREE_ONLY 0x02
252
+enum do_for_each_ref_flags {
253
+ /*
254
+ * Include broken references in a do_for_each_ref*() iteration, which
255
+ * would normally be omitted. This includes both refs that point to
256
+ * missing objects (a true repository corruption), ones with illegal
257
+ * names (which we prefer not to expose to callers), as well as
258
+ * dangling symbolic refs (i.e., those that point to a non-existent
259
+ * ref; this is not a corruption, but as they have no valid oid, we
260
+ * omit them from normal iteration results).
261
+ */
262
+ DO_FOR_EACH_INCLUDE_BROKEN = (1 << 0),
263
+
264
+ /*
265
+ * Only include per-worktree refs in a do_for_each_ref*() iteration.
266
+ * Normally this will be used with a files ref_store, since that's
267
+ * where all reference backends will presumably store their
268
+ * per-worktree refs.
269
+ */
270
+ DO_FOR_EACH_PER_WORKTREE_ONLY = (1 << 1),
271
+};
272
273
/*
274
* Reference iterators
@@ -357,16 +371,12 @@ int is_empty_ref_iterator(struct ref_iterator *ref_iterator);
371
* Return an iterator that goes over each reference in `refs` for
372
* which the refname begins with prefix. If trim is non-zero, then
373
* trim that many characters off the beginning of each refname.
360
- * The output is ordered by refname. The following flags are supported:
361
- *
362
- * DO_FOR_EACH_INCLUDE_BROKEN: include broken references in
363
- * the iteration.
364
- *
365
- * DO_FOR_EACH_PER_WORKTREE_ONLY: only produce REF_TYPE_PER_WORKTREE refs.
374
+ * The output is ordered by refname.
375
*/
376
struct ref_iterator *refs_ref_iterator_begin(
377
struct ref_store *refs,
369
- const char *prefix, int trim, int flags);
378
+ const char *prefix, int trim,
379
+ enum do_for_each_ref_flags flags);
380
381
/*
382
* A callback function used to instruct merge_ref_iterator how to
@@ -454,10 +464,8 @@ void base_ref_iterator_free(struct ref_iterator *iter);
464
/*
465
* backend-specific implementation of ref_iterator_advance. For symrefs, the
466
* function should set REF_ISSYMREF, and it should also dereference the symref
457
- * to provide the OID referent. If DO_FOR_EACH_INCLUDE_BROKEN is set, symrefs
458
- * with non-existent referents and refs pointing to non-existent object names
459
- * should also be returned. If DO_FOR_EACH_PER_WORKTREE_ONLY, only
460
- * REF_TYPE_PER_WORKTREE refs should be returned.
467
+ * to provide the OID referent. It should respect do_for_each_ref_flags
468
+ * that were passed to refs_ref_iterator_begin().
469
*/
470
typedef int ref_iterator_advance_fn(struct ref_iterator *ref_iterator);
471