@matheusbsbs / matheus-bagliano / commits / 5ac95fee3d

refs: tidy up and adjust visibility of the `ref_update` flags

The constants used for `ref_update::flags` were rather disorganized: * The definitions in `refs.h` were not close to the functions that used them. * Maybe constants were defined in `refs-internal.h`, making them visible to the whole refs module, when in fact they only made sense for the files backend. * Their documentation wasn't very consistent and partly still referred to sha1s rather than oids. * The numerical values followed no rational scheme Fix all of these problems. The main functional improvement is that some constants' visibility is now limited to `files-backend.c`. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Michael Haggerty committed Nov 5, 2017 at 09:42 UTC 5ac95fee3d6f77867a627a713f9aa72dc32be18f
3 files changed +99 -80
refs.h
+39 -28
@@ -335,22 +335,6 @@ void warn_dangling_symrefs(FILE *fp, const char *msg_fmt,
335 */
336 int refs_pack_refs(struct ref_store *refs, unsigned int flags);
337
338 -/*
339 - * Flags controlling ref_transaction_update(), ref_transaction_create(), etc.
340 - * REF_NODEREF: act on the ref directly, instead of dereferencing
341 - * symbolic references.
342 - *
343 - * Other flags are reserved for internal use.
344 - */
345 -#define REF_NODEREF 0x01
346 -#define REF_FORCE_CREATE_REFLOG 0x40
347 -
348 -/*
349 - * Flags that can be passed in to ref_transaction_update
350 - */
351 -#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
352 - (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
353 -
338 /*
339 * Setup reflog before using. Fill in err and return -1 on failure.
340 */
@@ -478,22 +462,23 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
462 *
463 * refname -- the name of the reference to be affected.
464 *
481 - * new_sha1 -- the SHA-1 that should be set to be the new value of
482 - * the reference. Some functions allow this parameter to be
465 + * new_oid -- the object ID that should be set to be the new value
466 + * of the reference. Some functions allow this parameter to be
467 * NULL, meaning that the reference is not changed, or
484 - * null_sha1, meaning that the reference should be deleted. A
468 + * null_oid, meaning that the reference should be deleted. A
469 * copy of this value is made in the transaction.
470 *
487 - * old_sha1 -- the SHA-1 value that the reference must have before
471 + * old_oid -- the object ID that the reference must have before
472 * the update. Some functions allow this parameter to be NULL,
473 * meaning that the old value of the reference is not checked,
490 - * or null_sha1, meaning that the reference must not exist
474 + * or null_oid, meaning that the reference must not exist
475 * before the update. A copy of this value is made in the
476 * transaction.
477 *
478 * flags -- flags affecting the update, passed to
495 - * update_ref_lock(). Can be REF_NODEREF, which means that
496 - * symbolic references should not be followed.
479 + * update_ref_lock(). Possible flags: REF_NODEREF,
480 + * REF_FORCE_CREATE_REFLOG. See those constants for more
481 + * information.
482 *
483 * msg -- a message describing the change (for the reflog).
484 *
@@ -509,11 +494,37 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
494 */
495
496 /*
512 - * Add a reference update to transaction. new_oid is the value that
513 - * the reference should have after the update, or null_oid if it
514 - * should be deleted. If new_oid is NULL, then the reference is not
515 - * changed at all. old_oid is the value that the reference must have
516 - * before the update, or null_oid if it must not have existed
497 + * The following flags can be passed to ref_transaction_update() etc.
498 + * Internally, they are stored in `ref_update::flags`, along with some
499 + * internal flags.
500 + */
501 +
502 +/*
503 + * Act on the ref directly; i.e., without dereferencing symbolic refs.
504 + * If this flag is not specified, then symbolic references are
505 + * dereferenced and the update is applied to the referent.
506 + */
507 +#define REF_NODEREF (1 << 0)
508 +
509 +/*
510 + * Force the creation of a reflog for this reference, even if it
511 + * didn't previously have a reflog.
512 + */
513 +#define REF_FORCE_CREATE_REFLOG (1 << 1)
514 +
515 +/*
516 + * Bitmask of all of the flags that are allowed to be passed in to
517 + * ref_transaction_update() and friends:
518 + */
519 +#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
520 + (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
521 +
522 +/*
523 + * Add a reference update to transaction. `new_oid` is the value that
524 + * the reference should have after the update, or `null_oid` if it
525 + * should be deleted. If `new_oid` is NULL, then the reference is not
526 + * changed at all. `old_oid` is the value that the reference must have
527 + * before the update, or `null_oid` if it must not have existed
528 * beforehand. The old value is checked after the lock is taken to
529 * prevent races. If the old value doesn't agree with old_oid, the
530 * whole transaction fails. If old_oid is NULL, then the previous
refs/files-backend.c
+45
@@ -10,6 +10,51 @@
10 #include "../object.h"
11 #include "../dir.h"
12
13 +/*
14 + * This backend uses the following flags in `ref_update::flags` for
15 + * internal bookkeeping purposes. Their numerical values must not
16 + * conflict with REF_NODEREF, REF_FORCE_CREATE_REFLOG, REF_HAVE_NEW,
17 + * REF_HAVE_OLD, or REF_ISPRUNING, which are also stored in
18 + * `ref_update::flags`.
19 + */
20 +
21 +/*
22 + * Used as a flag in ref_update::flags when a loose ref is being
23 + * pruned. This flag must only be used when REF_NODEREF is set.
24 + */
25 +#define REF_ISPRUNING (1 << 4)
26 +
27 +/*
28 + * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
29 + * refs (i.e., because the reference is about to be deleted anyway).
30 + */
31 +#define REF_DELETING (1 << 5)
32 +
33 +/*
34 + * Used as a flag in ref_update::flags when the lockfile needs to be
35 + * committed.
36 + */
37 +#define REF_NEEDS_COMMIT (1 << 6)
38 +
39 +/*
40 + * Used as a flag in ref_update::flags when we want to log a ref
41 + * update but not actually perform it. This is used when a symbolic
42 + * ref update is split up.
43 + */
44 +#define REF_LOG_ONLY (1 << 7)
45 +
46 +/*
47 + * Used as a flag in ref_update::flags when the ref_update was via an
48 + * update to HEAD.
49 + */
50 +#define REF_UPDATE_VIA_HEAD (1 << 8)
51 +
52 +/*
53 + * Used as a flag in ref_update::flags when the loose reference has
54 + * been deleted.
55 + */
56 +#define REF_DELETED_LOOSE (1 << 9)
57 +
58 struct ref_lock {
59 char *ref_name;
60 struct lock_file lk;
refs/refs-internal.h
+15 -52
@@ -8,58 +8,22 @@
8 */
9
10 /*
11 - * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
12 - * refs (i.e., because the reference is about to be deleted anyway).
11 + * The following flags can appear in `ref_update::flags`. Their
12 + * numerical values must not conflict with those of REF_NODEREF and
13 + * REF_FORCE_CREATE_REFLOG, which are also stored in
14 + * `ref_update::flags`.
15 */
14 -#define REF_DELETING 0x02
16
17 /*
17 - * Used as a flag in ref_update::flags when a loose ref is being
18 - * pruned. This flag must only be used when REF_NODEREF is set.
18 + * The reference should be updated to new_sha1.
19 */
20 -#define REF_ISPRUNING 0x04
20 +#define REF_HAVE_NEW (1 << 2)
21
22 /*
23 - * Used as a flag in ref_update::flags when the reference should be
24 - * updated to new_sha1.
23 + * The current reference's value should be checked to make sure that
24 + * it agrees with old_sha1.
25 */
26 -#define REF_HAVE_NEW 0x08
27 -
28 -/*
29 - * Used as a flag in ref_update::flags when old_sha1 should be
30 - * checked.
31 - */
32 -#define REF_HAVE_OLD 0x10
33 -
34 -/*
35 - * Used as a flag in ref_update::flags when the lockfile needs to be
36 - * committed.
37 - */
38 -#define REF_NEEDS_COMMIT 0x20
39 -
40 -/*
41 - * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a
42 - * value to ref_update::flags
43 - */
44 -
45 -/*
46 - * Used as a flag in ref_update::flags when we want to log a ref
47 - * update but not actually perform it. This is used when a symbolic
48 - * ref update is split up.
49 - */
50 -#define REF_LOG_ONLY 0x80
51 -
52 -/*
53 - * Internal flag, meaning that the containing ref_update was via an
54 - * update to HEAD.
55 - */
56 -#define REF_UPDATE_VIA_HEAD 0x100
57 -
58 -/*
59 - * Used as a flag in ref_update::flags when the loose reference has
60 - * been deleted.
61 - */
62 -#define REF_DELETED_LOOSE 0x200
26 +#define REF_HAVE_OLD (1 << 3)
27
28 /*
29 * Return the length of time to retry acquiring a loose reference lock
@@ -141,23 +105,22 @@ int copy_reflog_msg(char *buf, const char *msg);
105 * not exist before update.
106 */
107 struct ref_update {
144 -
108 /*
146 - * If (flags & REF_HAVE_NEW), set the reference to this value:
109 + * If (flags & REF_HAVE_NEW), set the reference to this value
110 + * (or delete it, if `new_oid` is `null_oid`).
111 */
112 struct object_id new_oid;
113
114 /*
115 * If (flags & REF_HAVE_OLD), check that the reference
152 - * previously had this value:
116 + * previously had this value (or didn't previously exist, if
117 + * `old_oid` is `null_oid`).
118 */
119 struct object_id old_oid;
120
121 /*
157 - * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF,
158 - * REF_DELETING, REF_ISPRUNING, REF_LOG_ONLY,
159 - * REF_UPDATE_VIA_HEAD, REF_NEEDS_COMMIT, and
160 - * REF_DELETED_LOOSE:
122 + * One or more of REF_NODEREF, REF_FORCE_CREATE_REFLOG,
123 + * REF_HAVE_NEW, REF_HAVE_OLD, or backend-specific flags.
124 */
125 unsigned int flags;
126