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>

diff --git a/refs.h b/refs.h
index 4ffef9502d1278880a33a032e3db2e7fe095a433..261d46c10cd49532b161a7a6bad69a677c7b65ab 100644 (file)
--- a/refs.h
+++ b/refs.h
@@ -335,22 +335,6 @@ void warn_dangling_symrefs(FILE *fp, const char *msg_fmt,
  */
 int refs_pack_refs(struct ref_store *refs, unsigned int flags);
 
  */
 int refs_pack_refs(struct ref_store *refs, unsigned int flags);
 

-/*
- * Flags controlling ref_transaction_update(), ref_transaction_create(), etc.
- * REF_NODEREF: act on the ref directly, instead of dereferencing
- *              symbolic references.
- *
- * Other flags are reserved for internal use.
- */
-#define REF_NODEREF    0x01
-#define REF_FORCE_CREATE_REFLOG 0x40
-
-/*
- * Flags that can be passed in to ref_transaction_update
- */
-#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
-       (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
-

 /*
  * Setup reflog before using. Fill in err and return -1 on failure.
  */
 /*
  * Setup reflog before using. Fill in err and return -1 on failure.
  */


@@ -478,22 +462,23 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
  *
  *     refname -- the name of the reference to be affected.
  *
  *
  *     refname -- the name of the reference to be affected.
  *

- *     new_sha1 -- the SHA-1 that should be set to be the new value of
- *         the reference. Some functions allow this parameter to be
+ *     new_oid -- the object ID that should be set to be the new value
+ *         of the reference. Some functions allow this parameter to be

  *         NULL, meaning that the reference is not changed, or
  *         NULL, meaning that the reference is not changed, or

- *         null_sha1, meaning that the reference should be deleted. A
+ *         null_oid, meaning that the reference should be deleted. A

  *         copy of this value is made in the transaction.
  *
  *         copy of this value is made in the transaction.
  *

- *     old_sha1 -- the SHA-1 value that the reference must have before
+ *     old_oid -- the object ID that the reference must have before

  *         the update. Some functions allow this parameter to be NULL,
  *         meaning that the old value of the reference is not checked,
  *         the update. Some functions allow this parameter to be NULL,
  *         meaning that the old value of the reference is not checked,

- *         or null_sha1, meaning that the reference must not exist
+ *         or null_oid, meaning that the reference must not exist

  *         before the update. A copy of this value is made in the
  *         transaction.
  *
  *     flags -- flags affecting the update, passed to
  *         before the update. A copy of this value is made in the
  *         transaction.
  *
  *     flags -- flags affecting the update, passed to

- *         update_ref_lock(). Can be REF_NODEREF, which means that
- *         symbolic references should not be followed.
+ *         update_ref_lock(). Possible flags: REF_NODEREF,
+ *         REF_FORCE_CREATE_REFLOG. See those constants for more
+ *         information.

  *
  *     msg -- a message describing the change (for the reflog).
  *
  *
  *     msg -- a message describing the change (for the reflog).
  *


@@ -509,11 +494,37 @@ struct ref_transaction *ref_transaction_begin(struct strbuf *err);
  */
 
 /*
  */
 
 /*

- * Add a reference update to transaction. new_oid is the value that
- * the reference should have after the update, or null_oid if it
- * should be deleted. If new_oid is NULL, then the reference is not
- * changed at all. old_oid is the value that the reference must have
- * before the update, or null_oid if it must not have existed
+ * The following flags can be passed to ref_transaction_update() etc.
+ * Internally, they are stored in `ref_update::flags`, along with some
+ * internal flags.
+ */
+
+/*
+ * Act on the ref directly; i.e., without dereferencing symbolic refs.
+ * If this flag is not specified, then symbolic references are
+ * dereferenced and the update is applied to the referent.
+ */
+#define REF_NODEREF (1 << 0)
+
+/*
+ * Force the creation of a reflog for this reference, even if it
+ * didn't previously have a reflog.
+ */
+#define REF_FORCE_CREATE_REFLOG (1 << 1)
+
+/*
+ * Bitmask of all of the flags that are allowed to be passed in to
+ * ref_transaction_update() and friends:
+ */
+#define REF_TRANSACTION_UPDATE_ALLOWED_FLAGS \
+       (REF_NODEREF | REF_FORCE_CREATE_REFLOG)
+
+/*
+ * Add a reference update to transaction. `new_oid` is the value that
+ * the reference should have after the update, or `null_oid` if it
+ * should be deleted. If `new_oid` is NULL, then the reference is not
+ * changed at all. `old_oid` is the value that the reference must have
+ * before the update, or `null_oid` if it must not have existed

  * beforehand. The old value is checked after the lock is taken to
  * prevent races. If the old value doesn't agree with old_oid, the
  * whole transaction fails. If old_oid is NULL, then the previous
  * beforehand. The old value is checked after the lock is taken to
  * prevent races. If the old value doesn't agree with old_oid, the
  * whole transaction fails. If old_oid is NULL, then the previous

diff --git a/refs/files-backend.c b/refs/files-backend.c
index a47771e4d43a61f168a28d7b462ff8cb747d3ff1..bbeafe1db7cd35bcd06688751c918cc6b6649af9 100644 (file)
--- a/refs/files-backend.c
+++ b/refs/files-backend.c
@@ -10,6 +10,51 @@
 #include "../object.h"
 #include "../dir.h"
 
 #include "../object.h"
 #include "../dir.h"
 

+/*
+ * This backend uses the following flags in `ref_update::flags` for
+ * internal bookkeeping purposes. Their numerical values must not
+ * conflict with REF_NODEREF, REF_FORCE_CREATE_REFLOG, REF_HAVE_NEW,
+ * REF_HAVE_OLD, or REF_ISPRUNING, which are also stored in
+ * `ref_update::flags`.
+ */
+
+/*
+ * Used as a flag in ref_update::flags when a loose ref is being
+ * pruned. This flag must only be used when REF_NODEREF is set.
+ */
+#define REF_ISPRUNING (1 << 4)
+
+/*
+ * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
+ * refs (i.e., because the reference is about to be deleted anyway).
+ */
+#define REF_DELETING (1 << 5)
+
+/*
+ * Used as a flag in ref_update::flags when the lockfile needs to be
+ * committed.
+ */
+#define REF_NEEDS_COMMIT (1 << 6)
+
+/*
+ * Used as a flag in ref_update::flags when we want to log a ref
+ * update but not actually perform it.  This is used when a symbolic
+ * ref update is split up.
+ */
+#define REF_LOG_ONLY (1 << 7)
+
+/*
+ * Used as a flag in ref_update::flags when the ref_update was via an
+ * update to HEAD.
+ */
+#define REF_UPDATE_VIA_HEAD (1 << 8)
+
+/*
+ * Used as a flag in ref_update::flags when the loose reference has
+ * been deleted.
+ */
+#define REF_DELETED_LOOSE (1 << 9)
+

 struct ref_lock {
        char *ref_name;
        struct lock_file lk;
 struct ref_lock {
        char *ref_name;
        struct lock_file lk;

diff --git a/refs/refs-internal.h b/refs/refs-internal.h
index b0f3e300c7fc494160cb846d22756f13abe4f10a..2ea02dcbe4a0f7dad1862bdf0c4bccdac6196ca5 100644 (file)
--- a/refs/refs-internal.h
+++ b/refs/refs-internal.h
@@ -8,58 +8,22 @@
  */
 
 /*
  */
 
 /*

- * Flag passed to lock_ref_sha1_basic() telling it to tolerate broken
- * refs (i.e., because the reference is about to be deleted anyway).
+ * The following flags can appear in `ref_update::flags`. Their
+ * numerical values must not conflict with those of REF_NODEREF and
+ * REF_FORCE_CREATE_REFLOG, which are also stored in
+ * `ref_update::flags`.

  */
  */

-#define REF_DELETING   0x02

 
 /*
 
 /*

- * Used as a flag in ref_update::flags when a loose ref is being
- * pruned. This flag must only be used when REF_NODEREF is set.
+ * The reference should be updated to new_sha1.

  */
  */

-#define REF_ISPRUNING  0x04
+#define REF_HAVE_NEW (1 << 2)

 
 /*
 
 /*

- * Used as a flag in ref_update::flags when the reference should be
- * updated to new_sha1.
+ * The current reference's value should be checked to make sure that
+ * it agrees with old_sha1.

  */
  */

-#define REF_HAVE_NEW   0x08
-
-/*
- * Used as a flag in ref_update::flags when old_sha1 should be
- * checked.
- */
-#define REF_HAVE_OLD   0x10
-
-/*
- * Used as a flag in ref_update::flags when the lockfile needs to be
- * committed.
- */
-#define REF_NEEDS_COMMIT 0x20
-
-/*
- * 0x40 is REF_FORCE_CREATE_REFLOG, so skip it if you're adding a
- * value to ref_update::flags
- */
-
-/*
- * Used as a flag in ref_update::flags when we want to log a ref
- * update but not actually perform it.  This is used when a symbolic
- * ref update is split up.
- */
-#define REF_LOG_ONLY 0x80
-
-/*
- * Internal flag, meaning that the containing ref_update was via an
- * update to HEAD.
- */
-#define REF_UPDATE_VIA_HEAD 0x100
-
-/*
- * Used as a flag in ref_update::flags when the loose reference has
- * been deleted.
- */
-#define REF_DELETED_LOOSE 0x200
+#define REF_HAVE_OLD (1 << 3)

 
 /*
  * Return the length of time to retry acquiring a loose reference lock
 
 /*
  * 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);
  * not exist before update.
  */
 struct ref_update {
  * not exist before update.
  */
 struct ref_update {

-

        /*
        /*

-        * If (flags & REF_HAVE_NEW), set the reference to this value:
+        * If (flags & REF_HAVE_NEW), set the reference to this value
+        * (or delete it, if `new_oid` is `null_oid`).

         */
        struct object_id new_oid;
 
        /*
         * If (flags & REF_HAVE_OLD), check that the reference
         */
        struct object_id new_oid;
 
        /*
         * If (flags & REF_HAVE_OLD), check that the reference

-        * previously had this value:
+        * previously had this value (or didn't previously exist, if
+        * `old_oid` is `null_oid`).

         */
        struct object_id old_oid;
 
        /*
         */
        struct object_id old_oid;
 
        /*

-        * One or more of REF_HAVE_NEW, REF_HAVE_OLD, REF_NODEREF,
-        * REF_DELETING, REF_ISPRUNING, REF_LOG_ONLY,
-        * REF_UPDATE_VIA_HEAD, REF_NEEDS_COMMIT, and
-        * REF_DELETED_LOOSE:
+        * One or more of REF_NODEREF, REF_FORCE_CREATE_REFLOG,
+        * REF_HAVE_NEW, REF_HAVE_OLD, or backend-specific flags.

         */
        unsigned int flags;
 
         */
        unsigned int flags;